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

[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

I want to create a handbook page containing guidelines for developers on
- 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).

[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

Post by Jennifer Hodgdon
Hi Bart,
These guidelines look pretty good to me, except possibly the last
"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

Post by Bart Feenstra
I want to create a handbook page containing guidelines for
- 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/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Jennifer Hodgdon]

My feeling is that it belongs in the module developers guide, but then
if there is a section of the Handbook that deals with UI in general
(or if someone creates one at a later date), you could always link
from that section to this page as well.

Or vice versa (put it in the UI section, if such a thing exists, and
link from the module developers guide).

You might also link to this page from the Documentation Style Guide
pages, as many of your guidelines relate to writing style.

--Jennifer

Post by Bart Feenstra
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 :)

[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 <

Post by 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
- 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/