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

[Charlie Lowe]

Well, the module name without .module after it is already displayed in 
the title. Also, on the modules page, it doesn't say book.module and 
page.module. So I wouldn't think the use of the .module is mandatory.

But I do think it is useful to orient the reader that they had know 
immediately that they are where they meant to go. So a keyword they 
could be looking for should be in the title or in that first sentence. 
In some cases it could be the module name; in others, this could be 
slightly different variations of the module name. For example, 
locale.module is listed in the administer menu as "localization." Since 
locale is already the admin/help page title, it might be good to orient 
them to the admin menu usage. Something similar for the book module. 
Someone may have heard the term "collaborative book." Book is already 
the title, so using "collaborative book" in the first sentence could 
provide additional orientation that they are indeed in the right place. 
In other cases, it may seem less techical to just use terms like "Drupal 
forums" or "private messaging"; opening up the style just a little to 
make things a touch more friendly helps the more non-tech savvy newbie.

So I think the answer in brief is that the first sentence should use the 
module name or a variation on that module name, depending on the situation.

Kieran Lal wrote:

 >
 > On May 14, 2005, at 12:08 AM, Charlie Lowe wrote:
 >
 >> "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.
 >>
 >>
 >
 > I didn't quite follow this.  How do you recommend we begin the fist 
paragraphs?
 >
 > See my on list post for the rest of my feedback.
 >
 > Cheers,
 > Kieran