[documentation] Text guidelines

[Stella Power]

I wonder if this module should be added as part of the coder module.  I
admit I haven't looked at the code, so can't say how easy that would be.
 It's probably not realistic to add it to Drupal 6 version of coder, but may
be possible for Drupal 7.
Cheers,
Stella

On Sat, Jun 6, 2009 at 9:35 AM, Bart Feenstra <
drupal-documentation at nederdev.nl> wrote:

> 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
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.drupal.org/pipermail/documentation/attachments/20090607/ff503390/attachment-0001.htm>