[documentation] Brainstorming a new documentation method

[add1sun]

These are definitely things we need to look at and discuss.  Steven  
has pointed out the major gotchas we have to contend with so this is  
some feedback in terms of the examples given and ideas tossed out here.

On Aug 22, 2007, at 3:22 PM, Tony Narlock wrote:

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

The categorization bit is something that needs to have a look over,  
both on d.o in general and the handbooks specifically.  I'll keep  
this to the handbooks since that is the microcosm we are really  
dealing with here (and note there are other movements afoot to redo  
d.o.)  As Steven noted he has begun work on pulling out some things  
that we would consider "core" documentation.  That process also  
involves re-organizing the material that is left from that separation  
and naturally leads to thinking about a more general re-org.  I have  
started to sketch out some thoughts on this and I gather that Steven  
will be posting more ideas on this very soon here.  Different people  
approach organization differently so I'm really curious about  
feedback on this one, but we should keep that to a thread  
specifically for that topic - hopefully started when Steven posts the  
things he's been working on.
>
> *Ruby-Doc.org* - http://www.ruby-doc.org/
> Eye candy, nice layout

There isn't really any eye-candy in the docs themselves since the  
links are all going off to other resources.  The page seems to simply  
be an aggregation of materials from around the web vs. on-site and  
consistently presented info.  One thing about "eye-candy" though is  
that now that Docs maintainers can add images to pages, it would be  
nice if started getting more screenshots and visuals up in our  
pages.  Other things like nice callout boxes and such would be nice  
but are dependent on the the theme and what level of HTML access  
folks have.
>
> *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'm not quite sure I follow on this one.  Yeah, our sidebar is pretty  
nasty when you are in a large section.  Looks like they are still  
putting the hierarchy in the sidebar on the PHP site though, just  
collapsing everything except the local section you are in, which on  
d.o would still be pretty long, depending where you are.  I can  
totally seethe collapsed "other stuff" as a point though.  We do also  
have local navigation in the "content" as all of the children for a  
section listed right on the page (see http://drupal.org/handbook/ 
config/contribmodules) - it is just underneath rather than at the  
top, which ends up being better if you have a huge list like the  
contrib modules.
>
> *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 hear what you are saying about the simplicity here but I have to  
disagree about just "finding related links".  The fact that we have  
context is a real plus in that I can go to the next page of the book  
and keep learning on this particular subject and know that the next  
and previous pages are related to what I'm reading now.  The TOC for  
big stuff is nice and right now on d.o you have to do that manually  
(see http://drupal.org/node/114774 for an example of where it is done  
- albeit not an article TOC but it is the same idea.)  We are using  
book module and unfortunately I don't see how we could automate TOC  
within a book page.
>
> *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.)

The versioned docs is a totally different ball of wax that we have  
been pondering for a while and Steven is in the process of starting.   
It is not a simple matter though for sure.  I notice there are no  
sidebars for navigation because the navigation is full pages for each  
level.  You have to drill down to what you want and then start  
reading.  But if I end up in the wrong place I have to back button my  
way back out (or go all the way to the TOC) and then go down another  
trail.  Just clicking around I managed to end up feeling a little  
lost when I tried to jump tracks since the TOC link at the bottom of  
the pages takes you to a different TOC than you start at when you go  
to a tab.  I do like the cleaner, simpler feel but I do miss the  
context  of where I am.
>
>
> 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.

I'm not sure it can be done with relative ease since some of this  
relies on the drupal.org theme and coming to an agreement about which  
changes we want to make and why.  We also must work using the book  
module and the tools we have on drupal.org which is not the full  
arsenal of a completely customized drupal site.
>
> 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).?

Definitely take a look at Steven's mail and blog.  We are moving in  
that direction but versioning is not something that is easily done  
and the way we will need to do it means that versioned docs will not  
be editable by the wider community at large since it will be in  
DocBook format and in CVS - not normal handbook pages.  Replicating  
the entire community-contributed handbook for each version is really  
not feasible at this time.  The editorial load to review and split  
all of it up would be absolutely astronomical and how would we handle  
one page that applies to multiple versions?  These are just a few of  
the problems.  It is definitely something that everyone would love to  
see but it gets pretty complicated when you try to sort out the details.

Thanks for taking the time to research some of this and present  
ideas.  I'd really like to see what feedback others have as well.   
Hopefully Steven will get his work out for discussion very soon so we  
can keep this rolling.
>
> Skiquel
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/