how can I help?

[Adam Williamson]

On Mon, 2009-07-20 at 15:28 -0400, Ricky Zhou wrote:
> On 2009-07-20 12:02:16 PM, Adam Williamson wrote:
> > I hate to be a stop-energy-spreader, but I'm not a big fan of the 'ten
> > thousand tiny pages' school of documentation. It winds up with two major
> > drawbacks: you can't ever find anything, and nothing gets updated.
> > (Visit the Gentoo wiki to observe both in operation).
> I think prioritizing documentation can help with this.  For example,
> a list of wiki pages/things that absolutely most be updated every
> release (does anything like this currently exist?)

I don't believe so. What I'd really like to see in this area would be
the smart use of templates (this is something Wikipedia does to some
extent); we could use these both to mark pages that will need regular
attention, and to do some kinds of stuff automatically (for instance, if
we had a {{version|current}} template - or something like that - it'd
help immensely; there are many pages which just want to mention the
number of the current release, for whatever reason. This may exist
without me knowing about it, I don't discount the possibility :>)

> I hate to keep picking on these few points, and this is not meant to put
> down our docs in any way, but I think the issue of
> 
> http://docs.fedoraproject.org/install-guide/f11/en-US/html/
> 
> vs.
> 
> http://en.opensuse.org/INSTALL_Local
> http://en.opensuse.org/Installation/11.1_Live_CD
> 
> is a very serious one.

> Where will the (currently nonexistent) docs about how to properly setup
> Apache go, for example?  I don't think we can get much worse than the
> kind of outdatedness that you get with:

These are both good examples; if that's the kind of thing you're talking
about I can't give a better idea than a Wiki / knowledge base article,
from a documentation perspective. There's an argument that this
information should be in the application documentation and if the
instructions for Fedora differ significantly from what the upstream
instructions are / should be, that's a bug...but that's a tricky area.

> Here's an example that happens to be commonly used in #fedora -
> currently the first search result for fedora sudo, I'm happy to say.
> 
> http://fedorasolved.org/post-install-solutions/sudo
> 
> This is the kind of documentation that I think we need for many common
> tasks.

Yeah, that's another good example. When I saw the word 'issues' I was
kind of keying on 'bugs'. I don't think a Wiki page for every little
task like this is a really awesome way to do things, but equally I've
never been able to come up with a better one :\

> Perhaps if each of our HOWTO pages had a header listing the applicable
> Fedora releases and date when the HOWTO was last updated?  I think that
> something would be better than the nothing that we have now.

A header's OK, but you can't get to that information very easily. I'm
sure we could think of something better, so we could have a way to know
very easily when a page might be out of date...

> I'm sorry for constantly regurgitating these same old examples, but I
> think they're indicative of where we currently stand in how the
> documentation that we have is presented to users, and I hope they show a
> few approaches that we can consider taking to improve the situation.

Nope, I certainly see where you're coming from, and I can't argue on
those examples.

-- 
Adam Williamson
Fedora QA Community Monkey
IRC: adamw | Fedora Talk: adamwill AT fedoraproject DOT org
http://www.happyassassin.net