Question Help Text Guidelines - Second draft

Only two and a half hours late this week!

webtrees guidelines for help text and other translatable strings.

SECOND DRAFT - Developers will discuss and another draft will be generated in a week.

Brevity

The maximum length of any single string should be a paragraph. Paragraph lengths vary but if it’s over seven sentences it probably should be split. A longer text is more likely to need a change and a re-translation.

Help pop-ups should be only a few small paragraphs (or even fewer large ones). Three hundred words of text with little white space takes up too much screen space for a pop-up. When a topic needs that much, look for a way to make it more than one topic, or just provide the basics with a link to a Wiki or other source.

A size guideline for pop-up vs. Wiki is To Be Determined. But for an example, UniGen.us/PGV/help_text.php?help=RESN_help is well-written, but it completely fills a full-screen FireFox on a 1280x800 MacBook screen. Probably a candidate for Wiki.

Readability

Help text should score 11.0 or less with a formula similar to the Flesch-Kincaid Grade Level. (The eleven loosely corresponds to the eleventh year of school in USA.)

When I first became a technical writer, our customer (U.S. Navy) would not accept any text with a Flesch-Kincaid score higher than tenth grade. A couple of years later, they changed their standard to eighth grade.

webtrees translators are pretty good in the base language—English—but it is not their native language. If we keep it simple, we make their job easier. And even for native speakers, changes needed are less likely to be noticed when the text is harder to read.

I pasted four samples of text into a single file. These were:

• An obituary partly by a grade-school teacher and partly by me
• The custom introduction on a PGV website
• The default webtrees introduction
• A preface to another genealogy website.

The combined file scored between 11 and 12 with the Flesch-Kincaid and other formulas. This draft of the guidelines scored about seven. Psalm 119 (New International Version) scores three, equivalent to about eight years old.

Flesch-Kincaid is not the only readability formula. The following will give more info about them and even measure text for you. Microsoft Word can also compute Flesch-Kincaid.

tinyurl.com/kvvx27
www.editcentral.com/gwt1/EditCentral.html
www.online-utility.org/english/readability_test_and_improve.jsp

Launchpad bug

A Launchpad bug causes a problem with text of more than 4096 characters. Comparing Psalm 119 in several languages, I found that Japanese has the largest file size (using UTF-. To keep Japanese below 4096 _bytes_ (not characters), the English needs to be less than 2850.

In my readability file, the longest paragraph was only 709 characters. Separating paragraphs is enough to avoid this bug.

Markup

Paragraphs should be enclosed in paragraph tags, not separated by break tags. This will aid translation, use of CSS for themes, and accessibility.

As much as possible, translation strings should not contain HTML tags. Put the translation call between the paragraph tags, not around them. Similarly for headings.

Avoid bold, italic, and font tags. Use headings, strong, and emphasis as intended so that accessibility and CSS can be used as they were intended.

Embedding

Filenames, URIs, image tags, and the like rarely need to be translated. Therefore, they should be inserted into strings by %s placeholders, like:
"click %s", '<input type="button" value="&gt;">'

Whitespace

If you need to list more than a few things, use a bulleted or numbered list.

Harder to read:
Family records could include subrecords for husband, wife, children, marriage, census, and more.

Better:
Family records could include subrecords for:

• husband
• wife
• children
• marriage
• census
• etc.

Consistency

Avoid confusion by using the same term every time the same concept comes up. For example, are we “persons” or “individuals”? These decisions should be documented in Wiki guidelines for each language, so that other developers or translators can be consistent.

“Special” characters

Use the actual character whenever possible

± %d years is easier to read than &amp;plusmn; %d years
&amp;plusmn; %d years is easier to read than &amp;#x00B1; %d years
&amp;#x00B1; %d years is easier to read than &amp;#177; %d years

The only browsers that can’t handle the actual character (given the correct encoding header) are either _very_ old or intentionally misconfigured.

Note: Greg dissents:

Not sure I agree with this one. Source files should not contain non-ascii characters.
We have to use other html entities, such as &amp;amp; and &amp;lt;. This is no different.

I personally think it is different (for reasons I’ll not offer unless asked). However, if no other developers have an opinion, I will change this section next draft (one week) to fit Greg’s.

Avoid fragments

Don’t create small bits of sentences and string them together. Different languages have different word orders. A translator needs to work with the entire sentence. Use a %d or %s placeholder if something within a sentence is variable.

Context

Use a context call when another language is likely to have different grammatical forms, e.g., gender, number, declensions, conjugations, etc.

Include an i18n comment when a fragment is necessary or a homonym/homophone is likely to be confusing (if a context call can’t be used). For example, “show” and “hide” can be opposite (verb) choices of a configuration setting, or they could be two unrelated nouns (one is on a stage, the other is on an animal). If they are in the same translation item, their meanings are obvious, but in independent items, context is needed.
===============
Gratuitous comment by Wes: Sometime prior to SVN 8601, the help text for RESN was rewritten to comply with the above guidelines for Brevity, Whitespoace, No fragments, and partially Markup. Compared to other help texts, it is MUCH easier to translate.

Please change "The eleven loosely corresponds to the eleventh year of school in USA" to something like "The eleven loosely corresponds to a 16-17 year old child", so the rest of the world has a chance at understanding what you are talking about

Please change "The eleven loosely corresponds …

Will do—but then won’t folks be thinking, “Why eleven?”

Surely that sentence exists to explain that? It would be a valid question if the paragraph was only:

Help text should score 11.0 or less with a formula similar to the Flesch-Kincaid Grade Level.

But perhaps the paragraph should be:

Help text should be designed to be readable by a 16-17 year old, measured by a score of 11 or less on a system like the Flesch-Kincaid Grade Level.

I think your second suggestion is better. Though it may be that one or more of the formulas cited doesn't use U.S. grade level.

Also, is that the age level you want? Or should it be lower? Or higher to keep out the riff-raff?

Perhaps some of you should select some text samples you feel are too easy, too hard, or just right, score them and see. Of course, you may not want to demand that writers quantify everything--but doing it occasionally may add insight.