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
Attachment:
pgpO9hFClY7YE.pgp
Description: PGP signature
-- fedora-docs-list mailing list fedora-docs-list@xxxxxxxxxx To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-docs-list
