[documentation] Text guidelines

[Bart Feenstra]

Hi Jennifer,

My intentions were to prevent explanations like "Recommended for live  
sites" and more verbose texts of the same kind. Unless a certain  
option has serious implications such an explanation should not be  
necessary.

I'm not yet sure where to add the handbook page. It is helpful to  
developers, but also to people who focus on UI stuff rather than  
writing texts. Suggestions about this are welcome :)

Best regards,

Bart

On Jun 7, 2009, at 17:14, Jennifer Hodgdon wrote:

> 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
>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/