[documentation] Brainstorming a new documentation method

[Tony Narlock]

I think with the coming power of the Drupal 6 API, a lot more 
possibilities will be open when it comes to making our documentation as 
easily accessible and intuitive as possible.

I would like to post a link to some random documentation sites that are 
used online. Try to find the pros and cons of them.

*MSDN Library* - http://msdn2.microsoft.com/en-us/library/default.aspx
I think the smaller fonts make things a bit easier to get around to. It 
may be harder to see, but it utilizes screen space far better. Also, 
they have their categories down pretty solid. Those are two aspects 
which are pluses, though I'm not sure if it's exactly what we want.

*Ruby-Doc.org* - http://www.ruby-doc.org/
Eye candy, nice layout

*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?

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

*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 think to create a good documentation we will need to mix the best part 
of all of these, while staying clean and being minimalist as possible.

I also think it is possible that our current system can undergo these 
improvements with relative ease. Furthermore, much of the problems lie 
purely in the interface and the way we are handling articles.

Example Proposal: Why not have a seperate handbook for 4.7, 5.x, and 
6.x? We don't just go out handing people "Windows Bible" without giving 
a specific type of information it is supposed to contain (Is it 95? 98? 
98SE? XP? 2000? All of them?). If we keep going at this rate our 
handbook will end up being filled to the brim with too much stuff.

That is my 2 cents.

Does anyone else here know any other good example of documentation for 
projects? Do you think we need to do a few tweaks before the 6.0 
release? What are your opinions on a handbook per major version (Perhaps 
accompanied with a universal handbook for concepts and what not).?

Skiquel