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

Thu Jan 11 18:48:03 UTC 2007

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:       patch (code needs review)

* Renamed "Contributing to the handbook" to "Major handbook sections"
* Moved "Commenting on the handbook pages" to under "Contributing to
documentation"
* Moved some of the pages on contributing to under "Contributing to
documentation"

I didn't want to touch /documentation-writers-guide (/node/336) because
it has a URL alias, and is a very old node. 

After Contributing to documentation [1] receives your review, some of
the other pages can be updated. 

-karldied 

[1] http://drupal.org//node/24572

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.

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

Tue, 09 Jan 2007 06:05:34 +0000 : karldied

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 [2] got no response? Also,
comments by new members such as drapulled's [3] 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

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

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

Tue, 09 Jan 2007 06:09:43 +0000 : karldied

Corrected link: my mailing list re-org suggestion [4]
[4]
http://lists.drupal.org/pipermail/documentation/2006-December/004847.htm...

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

Tue, 09 Jan 2007 09:44:45 +0000 : vjordan

+1 for karldied's suggestions.

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

Thu, 11 Jan 2007 18:19:47 +0000 : karldied

Steve (and others), 

I published the methods by which people can contribute to the
documentation handbooks at /node/24572, Contributing to documentation
[5]. It covers the _methods_ by which people contribute. (I subsumed the
one sentence page titled "Requests for new documentation and reporting
documentation problems" and moved it up one level in the hierarchy.)
Your edits are requested. 

My impression is that you are very busy, so I wrote how I suspect the
process will best work, and invite you and others to edit.

"File a bug report" is listed at the top so that newbies see it first,
since (my impression is) it is probably the best all-round method. 

I included such things as "post a forum topic" as a method of
contributing, so that newbies can understand why to not just post a
forum topic to request handbook updates, and so that it is clear where
forum posts fit into the scheme of things. 

The "Edit handbook pages" paragraph specifies filing bug reports to
request site administrator role updates. This paragraph particularly
deserves your editing depending on how you (senior doc team) want us
(members of your doc team) to propose and request these. 

-karldied

[5] http://drupal.org//node/24572