[documentation] Brainstorming a new documentation method

[Jason Flatt]

On Wednesday 22 August 2007 12:22:18 Tony Narlock wrote:
>
> *Ruby-Doc.org* - http://www.ruby-doc.org/
> Eye candy, nice layout

I agree with add1sun, it's only a front page.  Eye candy doesn't necessarily 
mean good documentation.

> *PHP Manual* - http://www.php.net/manual/en/install.php
> I think it's alot cleaner when the menu on the left is NOT hierarchical.
> Our sidebar on the documentation can go from a simple tree stump to a
> 2000 pixel long grand oak. It's ridiculous. Why not let the hierarchy be
> navigated through the $content instead of the sidebar?

I respectfully disagree.  I almost never (almost) use the sidebar navigation 
on php.net, because it frequently isn't helpful for me.  I almost always 
(almost) have to use the search interface to get I want.  If what I find 
isn't what I wanted, the sidebar navigation usually doesn't have it either, 
so I'm back to searching.

> *Wikibooks* - http://en.wikibooks.org/wiki/Note_taking (example)
> Wikibooks designed to make content the center of attention, the eyes
> gravitate toward the reading material. Pay attention to the use of a
> Table of contents for larger articles, and note that breadcrumbs and
> menus play no part in reading the handbook. People handle it fine.
>
> I think the overwhelming nature of our doc interface can make knowing
> exactly where you is sometimes harder than if you were just on a wiki
> finding relating links.

I like knowing where I am, and being able to jump around as necessary.  
Wikibooks don't really give me that.

> *Ubuntu Documentation* - https://help.ubuntu.com/
> Much cleaner. It's almost a joy to read through this, the fonts are big,
> but their is so much more space because there are no sidebars in the
> way. There is a documentation section that is for different versions.
> (Which is something we should consider in the long term, because without
> separate documentation per version, it can get pretty marshy in there.)

I agree with add1sun on this.

My 2 cents is that what is helpful to one person may not be helpful to other 
people (which is why there are so many different ways of documenting and 
navigating).  I use d.o's left sidebar navigation quite heavily.  I don't 
really like to use previous/next links, because I frequently feel like I'm 
jumping blind into an unknown area.  I want to be able to see the big picture 
and drill down or jump around, depending on what I'm reading or looking for, 
and previous/next links and start page TOC links don't really give me that.

The other thing is that w/o the navigation, you don't know what you're 
missing.  The search terms or search engine may not give you the documents 
you're looking for, and previous/next links won't help you if you're in the 
totally wrong area.


-- 
Jason Flatt
http://www.oadaeh.net/
Father of Six:  http://www.flattfamily.com/ (Joseph, 14; Cramer, 12; Travis, 
10; Angela; Harry, 7; and William, 12:04 am, 12-29-2005)
Linux User:     http://www.xubuntu.org/
Drupal Fanatic: http://drupal.org/