[documentation] [Documentation feature] Improvements needed for the Handbook - how to contribute

[karldied]

Issue status update for 
http://drupal.org/node/107005
Post a follow up: 
http://drupal.org/project/comments/add/107005

 Project:      Documentation
 Version:      <none>
 Component:    Misc
 Category:     feature requests
 Priority:     normal
 Assigned to:  sepeck
 Reported by:  zoon_unit
 Updated by:   karldied
 Status:       active

Contributing to the handbook [1] would be clearer to someone trying to
help if it enumerated the _methods_ by which contributions can be made
(see current paragraphs 2 and 3): 


1. Commenting on the handbook pages [2]
2. Filing an issue against a page
3. Adding a new page
4. Editing handbook pages (after becoming a handbook editor) 


There are a couple additional contribution how-tos that would help
handbook editors (or at least me): 


5. Reorganization suggestions


I suspect that handbook reorganization suggestions should be submitted
as issues since  my mailing list suggestion [1] got no response? Also,
comments by new members such as drapulled's [2] and calls for wikis
really seem to have, at their root, a call for improved handbook
organization. 


Importantly, what _format_ do you want these submissions in? 


6. Incorporating comments


After I edit a handbook page to incorporate good comments, what do I do
to get the comments purged? 


-karldied


[1] drupal.org/node/23743
[2] drupal.org/node/14345


[1]
http://drupal.org/lists.drupal.org/pipermail/documentation/2006-December...
[2] http://drupal.org//node/106309




karldied



Previous comments:
------------------------------------------------------------------------

Fri, 05 Jan 2007 04:51:48 +0000 : zoon_unit

In order to increase the participation and feedback from new users of
Drupal, the Handbook needs some improvements.



* The "About Drupal Documentation" section of the Handbook should be
weighted to appear at the top of the page.  This will bring the link
"Contributing to the Handbook" front and center.  Announcements could
also be posted on a regular basis on the forum to encourage and remind
users to contribute.
* Instructions for submitting documentation suggestions as issues
should be placed at the very top of the documentation page, ideally
under the Drupal handbooks title.  This will encourage suggestions from
new users on ways to improve documentation.  Perhaps a different color
or graphic can be used, similar to the orange box on the Drupal.org home
page.



------------------------------------------------------------------------

Fri, 05 Jan 2007 10:09:46 +0000 : sepeck

link to documentation added to /handbooks page.  The about Drupal and
the installation and configuration guides are still more important to
the general community then 'about drupal documentation'.  Link to
api.drupal.org added as well.


Suggestions on improving the phrasing appreciated.




------------------------------------------------------------------------

Fri, 05 Jan 2007 18:55:32 +0000 : zoon_unit

The API link is a great improvement.


A paragraph up top explaining the use of the issues feature for
documentation suggestions would be very helpful as a reminder,
especially for newbies.  For some reason, it's very easy to overlook the
issues option, even though it's listed right on the user's menu.


This is probably because most users associate issues with correcting
bugs rather than making feature requests and suggestions.




------------------------------------------------------------------------

Fri, 05 Jan 2007 19:07:34 +0000 : zoon_unit

I noticed that you do mention issues on the "Contributing to the Drupal
Handbook" page, but it only mentions using issues to report errors. 
Perhaps moving this paragraph up and encouraging visitors to submit
suggestions via the issues feature would be an improvement.