[documentation] Proposal for handbook maintenance automation

[Ben Feldman]

Tony Narlock wrote:
> 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 really like that idea. This way, comments with suggestions, questions, 
etc. have a more welcomed place. Plus, it kinda opens up the sort of 
"etiquette" of what's worth posting and what's not.
> I think my point is, maybe it's just me, but it's getting kinda messy 
> and crowded in there.
>   
Yes. I agree.
> 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).
>   
I know that the Ubuntu wiki has this exact system in place where there 
are tabs at the top of the page with the different versions of Ubuntu 
supported. While I guess it may be silly to have tabs for 4.6 or 4.7 at 
this point, we could certainly implement this once 6 comes out, the 
default tab being 6 with a tab for 5 for those who haven't switched over 
yet.
> 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.
>   
I tried this, and you're right--things do seem a lot clearer and more 
organized. 0.7em is not so small that the text is unreadable, but it 
makes things seem a lot less crowded.
> Just a few ideas
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>   
-- 
Ben Feldman
Director, Go FLOSS!
ben at go-floss.org