[documentation] Real newbie documentation

[Kim P. Werker]

I may be stepping in it, but has the group considered turning  
comments off on Handbook 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? 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.).

Which is far from where I started with my question about turning off  
comments. My morning coffee's sitting half full next to me.

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.