| 1 |
Hello, everyone. I have been using Gentoo for five years, and I have been continually impressed with the quality and quantity of documentation--especially the Handbook. However, one issue has been bothering me for a long time, and I feel that addressing it would dramatically improve the Gentoo user experience. I believe that the organization of docs on gentoo.org, and the navigation of documentation pages on gentoo.org, are poorly designed and result in inefficient access to the information. I realize this issue crosses over into the domain of the infrastructure team, but I'm starting with you. |
| 2 |
|
| 3 |
First, consider the homepage at www.gentoo.org. Look at the left nav bar. We have: |
| 4 |
|
| 5 |
Installation: |
| 6 |
---------------- |
| 7 |
Gentoo Handbook |
| 8 |
Installation Docs |
| 9 |
|
| 10 |
Documentation: |
| 11 |
---------------- |
| 12 |
Home |
| 13 |
Listing |
| 14 |
About Gentoo |
| 15 |
Philosophy |
| 16 |
Social Contract |
| 17 |
|
| 18 |
|
| 19 |
This is really confusing, and even after years of using Gentoo, I still have to hunt around to find out where to look. I propose to remove "About Gentoo", "Philosophy", and "Social Contract" from the Documentation heading, because they don't fit with everything else that we call docs. I propose to replace all of the above with the following simple structure: |
| 20 |
|
| 21 |
Documentation: |
| 22 |
---------------- |
| 23 |
Overview |
| 24 |
Gentoo Handbook |
| 25 |
Documentation Listing |
| 26 |
|
| 27 |
About: |
| 28 |
|
| 29 |
---------------- |
| 30 |
About Gentoo |
| 31 |
|
| 32 |
Philosophy |
| 33 |
|
| 34 |
Social Contract |
| 35 |
|
| 36 |
"Overview" links to the page http://www.gentoo.org/doc/en/index.xml |
| 37 |
"Gentoo Handbook" stays the same |
| 38 |
"Documentation Listing" stays the same |
| 39 |
|
| 40 |
The page "Installation Docs" is unnecessary--the paragraphs at the top are duplicates of the text on the "documentation home" page, and the links below are unneeded because the "Documentation Listing" has the installation docs conveniently grouped at the top of the list. |
| 41 |
|
| 42 |
Further, the page at http://www.gentoo.org/doc/en/index.xml is written in a confusing way. Consider the sentence, "If you want a quick overview of all available documentation without the additional information, please use our Documentation Listing page. We also have a full listing of all our documents with their descriptions." It contains two different links, that appear to go to different pages, but both point back to http://www.gentoo.org/doc/en/list.xml. |
| 43 |
|
| 44 |
On a slightly different note, I would suggest changing the look of the web pages in the Handbook, to give users a clear visual indication when they navigate away from the Handbook. |
| 45 |
|
| 46 |
Thank you for listening, and I would love to know how I can help you make the documentation better. |
| 47 |
|
| 48 |
Craig |
| 49 |
|
| 50 |
|
| 51 |
|
| 52 |
|
| 53 |
____________________________________________________________________________________ |
| 54 |
Never miss a thing. Make Yahoo your home page. |
| 55 |
http://www.yahoo.com/r/hs |
| 56 |
-- |
| 57 |
gentoo-doc@l.g.o mailing list |
Archives