how can I help?

[Ricky Zhou]

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 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.  Our organized, comprehensive docs definitely
have their place, but the unfortunate fact is that some new users will
be scared off by the table of contents alone.  This is where specific,
task-based documentation (with an eye towards the defaults) is very useful.

> Most issues that are encountered on #fedora or forums, for instance,
> should be documented in either the Common Issues page, or the Release
> Notes. This was mostly what my earlier (long) email to the list was
> about, which no-one seemed to reply to. I really think it's better to
> keep things in some semblance of organization in central, canonical
> pages, rather than having zillions of single-issue pages...
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:

http://www.google.com/search?q=fedora+apache

vs.

http://www.google.com/search?q=opensuse+apache

(this is also partially in response to your comment about docs being
hard to find)

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.

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.

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.

Thanks,
Ricky
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20090720/64617168/attachment.sig>