[documentation] Brainstorming a new documentation method

[Steven Peck]

I think you've missed my link to my blog post earlier this week
Core documentation per version is coming.
http://www.blkmtn.org/documentation-challenges-and-the-future
Note, this is limited to Drupal core.  I will also be doing a slight
re-wrote and re-org of it's structure.

This weekend I will also send a re-org proposal of the over all
documentation structure out as well to solicit comments/feedback on it
that I have been discussing as part of this.  You can see some
direction ideas from the comments on the link.

One reason against docs.drupal.org is then the content would not be
search-able in with the rest of the site.  You'd have to search both
the main site (forums, etc) and a docs site.  This is still not out of
the realm of long term possibility, just short term rest of the year
not going to happen (more resource then anything else).  There are
other discussions on an overall re-org of drupal.org that are ongoing.

One thing that is an outstanding issue for me with the Blue Beach
theme is the right sidebar floats over content and getting rid of it
is hard.  Adding images is problematic and you have to use print view
to see them.  webchick tried her hand at getting rid of them on the
handbook pages but it proved problematic.  I personally don't like
right hand navigation on sites as it limits content area.

Think in these terms.  There are 3 stages.
1.  Core docs (see my blog)
2.  Short term re-org (1-2 months maybe sooner)
3.  Long term drupal.org structure which can involve theme suggestions as well.

-sp

On 8/22/07, Tony Narlock <skiquel at mac.com> 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.
>
> *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
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>