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

  1. 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.
  2. 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.

Comments

sepeck’s picture

sepeck commented

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.

sepeck’s picture

sepeck commented
Assigned: Unassigned » sepeck
zoon_unit’s picture

zoon_unit commented

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.

zoon_unit’s picture

zoon_unit commented

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.

karldied’s picture

karldied commented
Title: Improvements needed for the Handbook » Improvements needed for the Handbook - how to contribute

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

karldied’s picture

karldied commented

Corrected link: my mailing list re-org suggestion

vjordan’s picture

vjordan commented

+1 for karldied's suggestions.

karldied’s picture

karldied commented
Status: Active » Needs review

Steve (and others),

I published the methods by which people can contribute to the documentation handbooks at /node/24572, Contributing to documentation. 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

karldied’s picture

karldied commented

* 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 receives your review, some of the other pages can be updated.

-karldied

karldied’s picture

karldied commented

Although the decision was made to keep the "About Drupal documentation" handbook at the bottom of the list, I think the matter of how to contribute to doc is essentially solved.

Compiled and wrote: Contributing to documentation, http://drupal.org/node/24572
Wrote: Documentation issue reports, http://drupal.org/node/24565
Updated: Commenting on handbook pages, http://drupal.org/node/14345
Compiled and wrote: Joining the documentation team, http://drupal.org/node/23367
Updated: Handbook style guide, http://drupal.org/about/authoring
Re-wrote: Documentation writer's guide, http://drupal.org/documentation-writers-guide

Obviously, with a lot of input and refinement. Steve also completed other pages, such as
Handbook maintainers, http://drupal.org/node/109372

I invite this issue to be updated to "fixed." -karldied

karldied’s picture

karldied commented
Status: Needs review » Fixed
Anonymous’s picture

(not verified) commented
Status: Fixed » Closed (fixed)