[documentation] Navigability on Drupal documentation

[Larry Garfield]

On Sunday 25 June 2006 12:51, Luiz wrote:

> > On the other hand, one advantage of the book module over a wiki is that
> > a page creator must choose where to put new documentation within an
> > existing structure and can still link to other pages as well.
>
> I agree with you, it's necessary to give adequate tool to a maintainer
> to facilite your job. However, a documentation is writed to final users,
> essentialy. And users need a clean, rapid and efficent manner to found
> what the users are searching. Wikis are good to this.

Actually, I have found wikis to be generally terrible for large-scale 
documentation.  Their free-form nature means that you are entirely at the 
whim of each individual page author to decide what should be read "next" or 
what is related.  A book structure has a natural flow, from reading an 
introduction to a more detailed page to a more detailed page to a more 
detailed page.  It also works better when you have a multi-step process 
spread over a couple of pages, since the "next" functionality is built-in.

Wikis are useful if and only if your primary means of locating information is 
a keyword search, and you have a really good keyword indexing system.  The 
former is very often not true of Drupal's documentation, and the latter, 
well, Drupal doesn't quite have yet, sorry. :-)

I've never, ever seen a wiki site I liked besides Wikipedia itself.  The 
others all suck.

That doesn't mean Drupal's docs don't need improvement.  They do.  Many common 
pages need to have an alias assigned to them that don't.  (See the issue 
queue.)  But moving to a wiki is a step backward, IMHO.

-- 
Larry Garfield			AIM: LOLG42
larry at garfieldtech.com		ICQ: 6817012

"If nature has made any one thing less susceptible than all others of 
exclusive property, it is the action of the thinking power called an idea, 
which an individual may exclusively possess as long as he keeps it to 
himself; but the moment it is divulged, it forces itself into the possession 
of every one, and the receiver cannot dispossess himself of it."  -- Thomas 
Jefferson