Linux Archive

Linux Archive (http://www.linux-archive.org/)
-   Gentoo Documentation (http://www.linux-archive.org/gentoo-documentation/)
-   -   Organization of documentation on gentoo.org (http://www.linux-archive.org/gentoo-documentation/41260-organization-documentation-gentoo-org.html)

Craig Finch 01-18-2008 11:40 PM

Organization of documentation on gentoo.org
 
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.

First, consider the homepage at www.gentoo.org. Look at the left nav bar. We have:

Installation:
----------------
Gentoo Handbook
Installation Docs

Documentation:
----------------
Home
Listing
About Gentoo
Philosophy
Social Contract


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:

Documentation:
----------------
Overview
Gentoo Handbook
Documentation Listing

about:

----------------
About Gentoo

Philosophy

Social Contract

"Overview" links to the page http://www.gentoo.org/doc/en/index.xml
"Gentoo Handbook" stays the same
"Documentation Listing" stays the same

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.

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.

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.

Thank you for listening, and I would love to know how I can help you make the documentation better.

Craig




__________________________________________________ __________________________________
Never miss a thing. Make Yahoo your home page.
http://www.yahoo.com/r/hs
--
gentoo-doc@lists.gentoo.org mailing list

Jose Luis Rivero 01-19-2008 12:49 AM

Organization of documentation on gentoo.org
 
Hi Craig:

On Fri, Jan 18, 2008 at 04:40:24PM -0800, Craig Finch wrote:
> 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:
>
> Documentation:
> ----------------
> Overview
> Gentoo Handbook
> Documentation Listing
>
> about:
>
> ----------------
> About Gentoo
>
> Philosophy
>
> Social Contract
>
> "Overview" links to the page http://www.gentoo.org/doc/en/index.xml
> "Gentoo Handbook" stays the same
> "Documentation Listing" stays the same
>

I agree with you in this new layout but I would like to make some
considerations to your idea:

> 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.

"Installation Docs" is (talking about xml source) the same page as
"documentation home" (index.xml) this is the reason why you see the same
(but not duplicated) text.

I really like the "Installation Docs" page, which gives the user a quick
overview about the diferents levels and options we offer to install
Gentoo and not only the well-known handbook. The quick-guides for non
new users, the lot of times forgotten networless handbook and some more
advanced or exotic options like raid+lvm, bsd or alternative
installation guide.

I'm for keeping this link but I'm also for keeping the number of documentation
main page links in three so .. my vote goes to change handbook direct
link to this one. We would keep the handbook as the main option since is
the first link in this page.

Another good option to me is to use the documentation listing in full
mode (list.xml?desc=1) which gives a more elaborated image (and provides
extra information) than lots of categorized links with no further description.

Thanks.

--
Jose Luis Rivero <yoswink@gentoo.org>
Gentoo/Doc Gentoo/Alpha

--
gentoo-doc@lists.gentoo.org mailing list


All times are GMT. The time now is 07:29 AM.

VBulletin, Copyright ©2000 - 2014, Jelsoft Enterprises Ltd.
Content Relevant URLs by vBSEO ©2007, Crawlability, Inc.