[documentation] Text guidelines

[Bart Feenstra]

Hi all!

The last weeks I have been busy working on UX stuff in Drupal. Part of  
the work I've done is rewrite texts - or remove them. A lot of texts  
in both core and contrib are unnecessary, too complicated and long or  
add redundant information to pages. I am working on http://drupal.org/project/atr 
  to automatically review texts used in the code (it will be able to  
review translations in the near future). Plans are to set it up on  
t.d.o when it's done and make it create text reviews of patches, like  
SimpleTest already tests patches, and existing code.

At this moment ATR checks for strings that contain blacklisted words  
and strings that are similar. I assume the idea behind a blacklist is  
known to all of you. The similarity check is intended to prevent  
(near) duplicate text from being used to improve consistency and  
decrease efforts needed to translate Drupal (Less _is_ more in this  
case).

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).

Some guidelines may seem so simple that one would assume everybody  
knows about them. They don't. A lot of developers are great at  
programming cool stuff, but find it hard to write proper texts or make  
good UIs. This handbook page is intended as an easy reference for  
those people.

Thanks for reading and please let me know what you think :)

Bart
Xano