[documentation] Text guidelines

[Jennifer Hodgdon]

Hi Bart,

These guidelines look pretty good to me, except possibly the last one 
-- and maybe it's just the wording:

"Don't tell users how they should use your stuff through the UI. Just
tell them what it does. Background information and tips belong in the
documentation (help texts, handbooks)."

People don't tend to read separate documentation, in my experience. So 
it seems to me that a sentence describing what to do at the top of the 
"Options" or "Setup" screen of a module can be helpful, and save 
people contacting the module maintainers for support. And putting 
short tips in the Description field is also useful. I do agree that 
lengthy descriptions belong in the main description, but maybe this 
guideline could be modified to say that concise tips have a place in 
the module itself?

Just a thought... Anyway, this seems like a good idea, and I look 
forward to seeing the Handbook page (I am assuming you're planning to 
add it to the module developers guide?). I hope the Handbook page has 
some examples, with better alternatives proposed, as illustrations 
(especially for things like Advanced Options).

Regards,
    Jennifer

Bart Feenstra wrote (in part):
> I want to create a handbook page containing guidelines for developers on 
> writing texts. Proposals:
> - Avoid certain words or phrases (the blacklist, yet to be determined).
> - Prevent duplicate texts (the similarity check).
> - Don't use subordinate clauses unless absolutely necessary.
> - Form element descriptions are no must. In most cases a title should be 
> sufficient. If not, don't repeat the same thing the title explains to 
> the user already.
> - Don't use terms like "Advanced options". These don't tell the user 
> what it means, just that the writer thinks this stuff is rocket science. 
> Unfortunately nobody can tell you if you're a scientist capable of this 
> stuff until you actually view the options, rendering the label useless.
> - If you're not a native speaker of English, make sure your texts get 
> reviewed by someone who is. If you are, do the same.
> - Don't tell users how they should use your stuff through the UI. Just 
> tell them what it does. Background information and tips belong in the 
> documentation (help texts, handbooks).

-- 
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal, WordPress, and custom Web programming