[documentation] Brainstorming a new documentation method

[Steven Peck]

Oh and if it didn't come through as such.... Good starter discussion.

On 8/22/07, Steven Peck <sepeck at gmail.com> wrote:
> 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/
> >
>