[drupal-docs] [task] Review of "How to write admin/help documentation"

[Amazon]

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

 Project:      Documentation
 Version:      <none>
 Component:    Misc
 Category:     tasks
 Priority:     normal
 Assigned to:  Anonymous
 Reported by:  cel4145
 Updated by:   Amazon
-Status:       closed
+Status:       active

This really needs a thorough scrubbing.  Spelling errors, inaccuracies,
etc.


We need to think of all the steps involved in creating administration
help documentation and then prioritize them.  Then provide specific
pages for more details.


1. Get module and install it.  http://drupal.org/project/Modules
2. Experiment with module to discover how to administer it and how to
create something with it.
2a. Look under administer >> module name.
2b. Look under administer >> settings >> module name.
2c. Look under administer >> blocks to see if it has any custom blocks
with it.
2d. Look under administer >> access control to see if the module has
access permissions.  Enable the permissions for your user role.
2e. Look unders create content.
3. Discover if the module has other modules that it is dependent on. 
Read the INSTALL.txt, README, or UPDATE text files associated with the
module.  In general these files are your best source of information
from the developer for writing documentation.
4. If the module is dependent or uses other modules be sure to provide
a link to that dependent modules administration help.
5. If all else fails, read the code.  You don't have to be a PHP
programmer to read the code file and get some ideas of what the module
does.  Programmers leave comments in files, and _help text messages are
a good source of documentation hints for what the module can do.  Drupal
uses a hook that maps to URLs so if you see a function like admin_help
then chances are http://www.example.com/admin/help is going to have
something worth looking at.   If nothing else, the module programer
will appreciate your valiant effort at reading their code, and be more
willing to help you.
6.  Now that you have done module research it's time to start thinking
about writing the administration help documentation.  See here for more
details: http://drupal.org/node/24268




Amazon



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

Fri, 03 Jun 2005 20:59:56 +0000 : cel4145

I've posted a revision of Kieran's wiki Admin Help Writing Instructions
[1] into the Drupal handbook:


How to write admin/help documentation [2]


If Kieran and others who have helped with creating the admin/help would
review it and edit it as necessary, that would be great. I'm sure I
probably missed something :)
[1] http://dev.bryght.com/t/wiki/AdminHelpWritingInstructions
[2] http://drupal.org/node/24268




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

Tue, 30 Aug 2005 06:29:27 +0000 : sepeck

Looks good and no one else has reviewed it, so it must be.


-sp




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

Tue, 30 Aug 2005 16:20:54 +0000 : cel4145

Thanks! Marking closed.