[documentation] Real newbie documentation

[Kieran Lal]

On Jan 7, 2006, at 5:15 AM, 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?

Yes, we need to delete comments.  I worked on the 2nd and 3rd most  
commented pages and cleaned them out last night.  Each page had  
around 30 comments, in some cases going back to 2002.  I worked in  
#drupal to get others to confirm code samples worked and installed  
them myself to ensure the documentation was still up to date.  I  
argued if I can't use the the documentation to create running code  
then the documentation is at fault.  I moved a lot of improvements  
and code samples into the main pages out of the comments and linked  
forum posts.  I also tagged the pages as 4.6 or 4.5 and older in one  
case.

Comments make the handbook look sloppy.   At the same time there is a  
lot of wisdom and value in those comments.  It's a difficult task to  
extract what's useful and to run the code or configure a site to  
confirm the documentation.

However, it's also a privilege to use the wisdom of this community  
and raise the collective intelligence[1] of Drupal by improving the  
documentation.

Kieran

[1] http://www.accelerating.org/ac2004/slides/AC2004(Engelbart).ppt



-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.drupal.org/pipermail/documentation/attachments/20060107/9938f9c5/attachment.htm