Today I wanted to change my ALSA drivers from the in-kernel version to the standalone one (as the info from the .ebuild suggested). I remebered that this process should be described somewhere in ALSA guide (I didn't want to miss important kernel options). So I jumped straight into the "Gentoo Documentation Resources". Now this page puzzled me a bit. I've heard that some people, especially _some_ news columnists [no names ;-)] raised concerns that Gentoo documentation is hard to find. Now, now. I know that there IS a vast number of documents, but indeed there is some truth in their saying. Let me consider two main points. First and foremost, if I open the "Gentoo Documentation Resources" page, most of my browser screen is filled with the following: * "Available languages" subsection (it's not big actually, and that's ok) * "Introduction" (this may be well put later in the page) * "Documentation Repository" (a small, not very useable subsection, with only one important link, "Documentation Listing", and - best of all - a link to itself !!!) * and finally, the "Gentoo Linux Documentation" (the meat what a user in a hurry looks for). The important part, "Gentoo Linux Documentation" is NOT VISIBLE by default on my screen with 1024x768 resolution (most common in laptops right now). I know that scrolling down one page is not hard, but still... The first sight is most important, isn't it? (this applies not only to the documentation pages, but to boys looking at girls, potential buyers looking at the new model of a car, and so on... ;) The first look on the page should tell what's inside. The most important points should be on the 40-50% height from the top of the view. Now, they are hidden at the end. /End of the sub-topic. The "Introduction" subsection could well be changed into "Description" and put AFTER "Gentoo Linux Documentation". This wouldn't do much harm to it, and would enable the important section to be displayed earlier (higher). That's needed IMHO for better usability. Now to the second issue (the original one, which caused this bug report). The "Gentoo Linux Documentation" section contains merely 8 simple links to the documentation categories. A user staring at them doesn't have any clue where such a link would lead him/her to, nor what would be described there. Yes, I second the descriptive names, but going back to my original intent, how could I say if "ALSA Guide" is in the "Installation Related Resources" (somewhere in the kernel docs?), "Desktop Documentation Resources", or "System Administration Documentation"? Hard to tell. That could be answered in two ways: * I could click on every one of those links and search for the "ALSA" keyword. Suboptimal, if you ask me. * I could also click on the "Documentation Listing" page, which would answer my question in no time, but (a very strong issue) the "Documentation Listing" link is INVISIBLE on the page, from the usability point of view. It's almost indistinguishable from the surrounding text. What a user can see is 8-points long list of links. With no clue what should be done next. Therefore I propose a simple solution to the "no clue what to do with that list" problem. Please add under every link a small, comprehensive overview of what is in that category. Like: * Installation Related Resources (Handbook, Quick Install, Gentoo/FreeBSD, LVM2, Genkernel, Bluetooth, USB) * Gentoo Desktop Documentation Resources (X Server, nVidia, ATI, KDE, Gnome, Fluxbox, ALSA, Java, 3D Acceleration, Localization, UTF-8, Power Management) * Gentoo System Documentation (Portage, USE flags, Gentoolkit, Kernel Guide) You get the idea. And the amount of work is actually minimal (read on!). Reproducible: Always Steps to Reproduce: 1. Make sure you use 1024x768 resolution 2. Visit the http://www.gentoo.org/doc/en/index.xml page and see for yourself Actual Results: The important part of the index.xml file looks as following right now: <p class="chaphead"><span class="chapnum"><a name="doc_chap2">2. </a></span>Gentoo Linux Documentation</p> <ul> <li><a href="?catid=faq">Frequently Asked Questions</a></li> <li><a href="?catid=install">Installation Related Resources</a></li> <li><a href="?catid=desktop">Gentoo Desktop Documentation Resources</a></li> <li><a href="?catid=gentoo">Gentoo System Documentation</a></li> <li><a href="?catid=sysadmin">System Administration Documentation</a></li> <li><a href="?catid=gentoodev">Gentoo Development Documentation</a></li> <li><a href="?catid=project">Project Specific Documentation</a></li> <li><a href="?catid=other">Other Documentation</a></li> </ul> Expected Results: It could be changed into: <p class="chaphead"><span class="chapnum"><a name="doc_chap2">2. </a></span>Gentoo Linux Documentation</p> <ul> <li><a href="?catid=faq">Frequently Asked Questions</a></li> <li><a href="?catid=install">Installation Related Resources</a><br/> (Handbook, Quick Install, Gentoo/FreeBSD, LVM2, Genkernel, Bluetooth, USB)</li> <li><a href="?catid=desktop">Gentoo Desktop Documentation Resources</a> (X Server, nVidia, ATI, KDE, Gnome, Fluxbox, ALSA, Java, 3D Acceleration, Localization, UTF-8, Power Management)</li> <li><a href="?catid=gentoo">Gentoo System Documentation</a> (Portage, USE flags, Gentoolkit, Kernel Guide)</li> <li><a href="?catid=sysadmin">System Administration Documentation</a> (Printing, Cron, Sudo, Udev, Security Handbook, Kernel Upgrade, Router, LDAP, Samba, Apache, MySQL, Postfix, IPv6)</li> <li><a href="?catid=gentoodev">Gentoo Development Documentation</a> (Developer Handbook, Documentation Policy, XML Guide, CVS Tutorial)</li> <li><a href="?catid=project">Project Specific Documentation</a> (Gentoo/AMD64, Hardened Gentoo, SELinux, Translators Howto)</li> <li><a href="?catid=other">Other Documentation</a></li> </ul> And I really think that the text in the "Documentation Repository" subsection could be very well rephrased (at least on the main docs page) to: "A quick overview of all available documentation without the additional information is on the Documentation Listing page." or: "The Documentation Listing page contains a quick overview of all available documentation without the additional information." or even shorter: "Documentation Listing page contains an index of all available documentation." or maybe: "Full index of all available documentation without the additional information is on the Documentation Listing page." This could be also moved after the "2. Gentoo Linux Documentation" section, after all the links. This would emphasize the fact that on the "Documentation Listing" page there is something important that's worth browsing and/or searching. In the last variant the emphasis is put on the "_Full_ index" part. This is a very serious statement, so if the "Documentation Listing" page is not frequently updated, it's not really a full index any more. OTOH IIRC this page is probably autogenerated (or at least it could be), so this bold "Full index" statement can be easily supported. That's all. Thanks for reading!
I'd like to point out that most of the claims applies to the current state of Gentoo Website Redesign project: http://wwwredesign.gentoo.org/ and specifically its "Gentoo Documentation Resources" page: http://wwwredesign.gentoo.org/doc/en/index.xml
I personally feel this is much ado about nothing, but kicking it over to the docs team since this is their area. --kurt
(In reply to comment #2) > I personally feel this is much ado about nothing, but kicking it over to the > docs team since this is their area. Kicking away
