[documentation] Real newbie documentation

[Kieran Lal]

On Jan 7, 2006, at 9:32 AM, Kim P. Werker wrote:

> I may be stepping in it, but has the group considered turning  
> comments off on Handbook pages?

There is incredible value in those comments.  It's critical that we  
have those comments so we can improve the documentation.

What we need is more people helping to extract the value of those  
comments and updating the pages.
>
> The beauty of "official" documentation (by which I mean docs that  
> are linked to from the main menu navigation of a software site,  
> which implies to me that they're fairly final) is that it should be  
> definitive (within reason). I was very confused by the comments  
> when I first went to the Handbook for help. The comments made me  
> think the actual documentation wasn't thorough, and left me  
> confused as to where to go for help -- the Handbook page that was  
> about the topic I wanted to learn more about, or the forum, where  
> I'd essentially be shooting in the dark?
>
> Thinking bigger, with the upcoming release of 4.7 and this active  
> discussion about organizing and fleshing out, maybe it's the  
> perfect time to prevent further adding to the docs until they're  
> reorganized, cleaned up, and a defined list of issues and  
> assignments is made.
>
> In the past, has preparing docs in private been considered?

We do it all the time. It's unpublished documentation that's viewable  
by the site moderators.  http://drupal.org/handbook/modules was  
completely planned and iterated half a dozen times before going live  
on Drupal.org.

> This would maintain the group collaboration, ensure that docs are  
> clean before they're published, and prevent the Handbook from  
> getting out of control (by which I mean growing in unpredictable  
> ways or getting overrun with comments/issues, etc.).

The growth in unpredictable ways is what's so valuable.  Tools like  
http://drupal.org/handbook/comments, and http://drupal.org/handbook/ 
most-popular-pages are exactly what we need to manage this  
unpredictability.
>
> Which is far from where I started with my question about turning  
> off comments. My morning coffee's sitting half full next to me.

I do think that handbook pages should be editable Wiki style.   
Wikipedia has proven the value of this.   The real problem with  
handbook documentation is that the people who are able to improve the  
documentation are frequently unable to do so.

Kieran
>
> Cheers,
> Kim
>
> On 7-Jan-06, at 7:49 AM, Charlie Lowe wrote:
>
>>
>>
>> Bèr Kessels wrote:
>>> I am an active comment-deleter. I delete comments on an almost  
>>> daily basis. :) But often I feel like an ++sh+le doing that,  
>>> since I delete them for good. However, support is support. and  
>>> should not live as comments in the handbook. Is that attitude  
>>> good? Or should I be nicer and rather leave the comments?
>>
>> Good question. Leaving the comments encourages more people to use  
>> the handbook as support. Optimally, we will want to modify the  
>> handbook page to address the comment in some way before deleting  
>> them. Perhaps, and this is just an idea that came to mind, when  
>> there is not the time at the moment to change the handbook page, a  
>> documentation issue could be created with the relevant text from  
>> the comments so that someone could later on update the page. That  
>> would allow the comments to be cleaned more regulary.
>> --
>> Pending work: http://drupal.org/project/issues/documentation/
>> List archives: http://lists.drupal.org/pipermail/documentation/
>
> ---
> Editor
> Crochet me Online Magazine
> http://www.crochetme.com
>
> This is your brain on yarn.
>
>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>