[documentation] Proposal for handbook maintenance automation

[Tony Narlock]

Laura Scott wrote:
> On Aug 8, 2007, at 11:33 AM, Kieran Lal wrote:
>
>> I think all the documentation should be a wiki.  Click here to edit.  
>> Give admins the ability to lock pages, were necessary.
>>
>> The current status of having 50 comments on a page for something as 
>> critical how to upgrade your module to the next API version, is 
>> completely unacceptable.  We are forcing companies and admins to 
>> spend collectively millions of dollars on upgrading their sites 
>> between versions with inconsistent and unclear documentation. 
>
> Agree on this 100%.
>
> Something sepeck and I discussed at OSCMS was that all the versions 
> are intermingled, and that ideally we would have handbook views by 
> version number, and done in a way that avoids massive node duplication 
> in order to effect hierarchy.
>
> The handbooks are a particularly tough challenge. Wonder if what we 
> really need are tabbed views for each page, with each tab offering 
> potentially version-specific info. Even in a wiki, that approach might 
> be helpful from a usability standpoint. The tagging alone gets us part 
> of the way there.
>
> Laura
>
> ------------------------------------------------------------------------
>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
I think moving a bit closer to the wiki think may be smart. Does anyone 
here feel that the "New Forum Topics" block can make the documentation 
seem a little cluttered? Maybe we could free up space on the right for 
thumbnails/notes one day. Oh, and media fields for steamcasts from the 
dojo! I think those are two things that are simple enough. I have had 
some experience with using wiki on drupal and I will say this: it's not 
quite perfected yet. It's really more of a WIP (work in progress).

I think the idea of having a "talk page", or simply separating the 
comments into a tab is smart. I think we should consolidate the 
documents interface to keep it focused on the information. I know how 
community and support is so important, but I think documentation should 
be clean and not so busy feeling. Mediawiki's are really focused on the 
information at hand.

I think my point is, maybe it's just me, but it's getting kinda messy 
and crowded in there.

I think that tabbed thing is important, we can make that work if we 
wanted. And Kieran has a point I didn't think about before, there is a 
good point in legacy support. Some articles need a tab for every 
version, some only for some versions, some only are limited to one 
version (not nescessarily the latest).

Has anyone here considered shrinking the size of the text down in the 
docs? At least in the menus? If anyone here has firebug try shrinking 
the font-size of #contentwrapper from .8em to .7em and see if that makes 
things a bit clearer. Perhaps the docs or drupal.org can have a 
font-size changing javascript added at one point in time. Or the default 
font changed. Or both.

Just a few ideas