Improve contributed module help page

Amazon - December 13, 2007 - 16:22
Project:Google Highly Open Participation Contest (GHOP)
Component:Task idea
Category:feature request
Priority:normal
Assigned:Unassigned
Status:active
Description

This is for GHOP. Drupal has a standard for writing contributed module help pages. These pages are written in a format that they can easily be added inside the module code.

You can update a contributed module help page,http://drupal.org/handbook/config/contribmodules, to follow the standard format here: http://drupal.org/handbook/modules

You should download the latest version of the module. Examine the modules configuration and make note of blocks, menus which might be part of the module. Read the comments in the code and ensure you have the paths.

Reviewers should compare the final product to this page: http://drupal.org/handbook/modules/aggregator

Pick one of the module help page below:
http://drupal.org/node/186685
http://drupal.org/node/173093
http://drupal.org/node/144172
http://drupal.org/node/151044
http://drupal.org/node/174575
http://drupal.org/node/159031
http://drupal.org/node/161562
http://drupal.org/node/195035
http://drupal.org/node/168965
http://drupal.org/node/119604
http://drupal.org/node/192806
http://drupal.org/node/187234

#1

aclight - December 13, 2007 - 17:29
Title:Write contributed module help page» Improve contributed module help page

I kind of have mixed feelings about this task. I didn't look through all of the possible help pages suggested above, so I'm not sure how these were picked, but I don't think a handbook page will necessarily be improved just by reformatting it to meet some guideline. Standardization is nice, but at the same time if the module author writes a good documentation page the quality might be decreased if a student who doesn't really understand the module comes along and changes it.

But that aside, here are some more practical problems I see with this:
1. Students don't necessarily have the documentation maintainer role, so the task should either specify that they get that permission with a link for how to do that or should give another way for students to submit their work.

2. The "good" example given is http://drupal.org/handbook/modules/aggregator
On that page, menu choices are styled in bold, which matches what is said at http://drupal.org/node/24566. However, the documentation style guide says to use italics: http://drupal.org/about/authoring

Am I missing a subtlety here or do these two style directives clash? If so, that's a documentation issue that needs to be fixed separately, but it's potentially confusing for a student.

As for how to taskify this, my vote would be to specify the module for which the student should correct the documentation page. We can have 1 or 2 of these tasks available at any time, and as they get taken up and completed we can replace with a different module. Otherwise it gets a lot more difficult to coordinate having >1 instance of this task open at a time.

#2

aclight - December 13, 2007 - 17:31
Component:GHOP Task» Task idea

#3

kourge - January 18, 2008 - 05:58

This is a good concept, but the difficulty of this depends on which modules are chosen and how familiar the student is with the modules.

 
 

Drupal is a registered trademark of Dries Buytaert.