[documentation] Brainstorming a new documentation method

[Steven Jones]

I think one of the biggest things to take from this list that you've
compiled is that most of the sites are not trying to exist within the
parent products site.

The MSDN library looks very different from the site you'd go to to buy
the products it documents, for example.

There is so much infomation in the handbook on Drupal.org that it can
really hard to use on a small screen (1024x768) Also I hardly ever use
the left hand nav, you often find that the current page link is about
20,000 pixels down, not very easy to find and not worth bothering to
look for.

Maybe we need a docs.drupal.org that looks something like MSDN, it
would be awesome.

On 22/08/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/
>


-- 
Regards
Steven Jones