[drupal-docs] Round 2 of Documentation Sprint - Please advise on the admin help writing instructions

[Kieran Lal]

Hi,
        I have put together writing instructions: http:// 
dev.bryght.com/t/wiki/AdminHelpWritingInstructions

Here is a list of guidelines I have put together for writing admin  
help.  I would be good to pause at this point and get some discussion  
about writing instructions.  Most of the 60 admin help documents are  
at least consistent now.   If we can agree on some writing  
instructions then it will be much easier to make all the changes at  
once.
Do not provide instructions to tell the user to log in or enable the  
module. If the user is reading admin help then the module is enabled  
and they have authenticated to have administration priviledges.
Admin help links should be context sensitive into the administration  
interfaces, and therefore do not require instructions such as My  
Account >> Administer >> module >> settings. Just provide the direct  
link and label it appropriately. Those type of instructions are  
better used in longer documentation that is not able to provide  
context sensitive linking directly into a users own administration  
interfaces.
The admin help documentation should be brief, ideally a couple of  
paragraphs.
The admin help documentation should have a links section that is  
easily scannable for users so they can quickly navigate to relevant  
interfaces. Providing direct links improves usability by reducing  
errors in accomplishing the task of administrating a module.
The admin help documentation should have links to the new  
configuration and customization handbook module pages. Providing  
links to more documentation improves usability through the use of the  
technique of information hiding. By reducing the total amount of  
information presented to the user it is possible to reduce the users  
cognitive load and reduce their time on the task by facilitating them  
to navigate more rapidly to meet their needs. Also, links to the  
handbooks allows the Drupal documentation team the ability to improve  
the documentation used by users continuosly. Alternatively, admin  
help documentation requires an update to the code.
For consistency I have been starting the paragraphs with the "The  
modulename module ...." -comments??
The first paragraph should provide a description of the benefits to a  
newbie user, i.e. the Anita user persona.
The next paragraph(s) should provide a list of tasks that represent  
the most common benefits.
If the module is a content type should we link to create content type  
in the admin help text?  /node/add/type?
If the module requires access permissions to be set should we provide  
a link to the access permissions page?
If the link points to documenation then the link should be named the  
unique name of the page. The sentence pointing to the documentation  
should begin with the active verb read. For example, Read the  
configuration and customization handbook <a href = "" title = "module  
page">module page</a>.
If the content module has a page that displays all content of that  
type should we link to it?  i.e. /node/blog
Use the term post instead of node.
Cheers,
Kieran
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://drupal3.drupal.org/pipermail/documentation/attachments/20050514/448f1e51/attachment.htm