On Mon, Jul 20, 2009 at 03:28:18PM -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 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.
How much could we avoid that scare by tuning the table of contents to
look more like what you see in the corner of a yelp screen? I.e.,
chapter titles only, with a more detailed listing at the beginning of
the chapter itself? This doesn't solve everything, but incremental
steps help.
--
Paul W. Frields
http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
http://redhat.com/ - - - -
http://pfrields.fedorapeople.org/
irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug