[documentation] Adding a note to comments form on handbook pages

Joshua Brauer joshua at brauerranch.com
Fri Feb 15 22:30:19 UTC 2008


I've recently been on comment patrol trying to clean up comments on a  
couple of handbook pages a day. Though we won't go into measuring  
progress against goals I've made some progress.

This process led to one comment I encountered being made into an issue  
in the issue queue and being deleted from the handbook page. The user  
who posted the comment was subsequently upset that the comment was  
removed and that by posting the issue in the queue I would be given  
"credit" for authoring the information and that I have wronged them by  
usurping the issue.

With that background I've been reflecting on my first years in the  
community. I would say that until I got involved with the  
documentation effort I wasn't clear about the guidelines for  
commenting on handbook pages (http://drupal.org/node/14345). I would  
have, and probably did, merrily comment on handbook pages in  
inappropriate ways without knowing better. It is also not clear at  
times if items are handbook pages or forum items for example (yes I  
know it's in the breadcrumb but again I don't always look here and I'm  
pretty sure that I'm not the only one).

There are also pages that in hindsight I think might have been better  
in g.d.o or setup as a forum. http://drupal.org/node/120677 is a case  
in point where there are too many good ideas in the comments and it is  
a document that doesn't lend itself to having the discussion that  
evolved incorporated in the page itself. From the 'keeping the  
handbook pages clean' standpoint it would have been nice had that  
discussion taken place in another area of the site.

All this leads me to wonder about the merits of posting a notice on  
the comment form on handbook pages. I haven't roughed out the language  
but I'm thinking along these lines:

"This is a handbook page. Before commenting on this page please  
understand the guidelines concerning comments on handbook pages (http://drupal.org/node/14345 
). If your comment would better be submitted as an issue or forum  
please post in those locations. If your comment is an improvement to  
this page it may be incorporated into the page by the documentation  
team."

That's probably longer and not quite what we'd want to say but if  
there is traction for the idea I'll open an issue.

---------------------------
Joshua Brauer


Our lives as we lead them are passed on to others, whether in
physical or mental forms, tingeing all future lives together.
This should be enough for one who lives for truth and service
to his fellow passengers on the way. --- Luther Burbank

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 2427 bytes
Desc: not available
Url : http://lists.drupal.org/pipermail/documentation/attachments/20080215/d2ff3bad/attachment.bin 


More information about the documentation mailing list