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

[Charlie Lowe]

Here are a few suggestions:

"The admin help documentation should be brief, ideally a couple of 
paragraphs."

I think this should be more precise and stress a lack of repetition.

"The admin help documentation should be brief without repetition: 2 
paragraphs and a list of links"

Then follow it with the first paragraph, second paragraph, and the link 
definitions.

"For consistency I have been starting the paragraphs with the "The 
modulename module ...." -comments??"

The current admin help displays the module name (without .module 
afterwards) as the title.  Assuming that the revised admin help will 
follow this format, I would think it would be safe to say "collaborative 
book" or "Drupal forums"--as long as the keyword (not necessarily 
.module) is included in the first sentence as a cue to the reader.

Besides, Kieran, I thought you didn't like the term "module" ;)

"The first paragraph should provide a description of the benefits to a 
new user."

I would be more specific as to length (push it here again) and tone down 
the usability discourse just a touch: "In no more than 2 to 3 sentences, 
the first paragraph should clearly and succinctly describe the module 
through it's benefits to users."

"The next paragraph(s) should provide a list of tasks that represent the 
most common benefits."

I think the term "tasks" is misleading a little. For example, look at 
the tracker help (http://dev.bryght.com/t/wiki/TrackerHelp) which is 
very clearly defined, hits the important features, yet contains things 
that aren't tasks.

How about, "The second paragraph should provide an explanation of module 
features that will help users to accomplish the most common tasks."

Still not quite right, but I think closer.

"If the module is a content type should we link to create content type 
in the admin help text." If it's in paragraph 1 or 2 in context, link it 
there. Otherwise, yes, in the links area.

"If the module requires access permissions to be set should we provide a 
link to the access permissions page."  Same as previous.

"If the content module has page that displays all content of that type 
should we link to it?" Sams as previous.

Also, here are some style suggstions:

I think "Links" could be replaced with something else, such as "You can 
also." Then it's no longer necessary to repeatedly say "you can" as on 
the locale page and each link list item will begin with a verb which is 
good.

Then the "Read the documentation" stuff would not be part of the list 
(since it's not an action for configuring/using the module). If there is 
no administrative interface, precede the "Read documentation" sentence 
with that sentence.

Then it's no longer necessary to repeatedly say "you can" as on the 
locale page and each link list item will begin with a verb which is good.

As an example, I reformatted the comment module page along the lines of 
what you have suggested with what I have suggested, although the first 
part of the first sentence in the 2nd paragraph repeats what is in the 
list of links: http://dev.bryght.com/t/wiki/CommentHelp#preview

Does any of this help?

Also, couldn't we just develop this documentation on drupal.org in the 
handbook? Boris has said before that he likes the RSS of the wiki. But 
it's being noticed here which is the main communication method of the 
doc group.



Kieran Lal wrote:
> 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
>