Question Help Text Guidelines - Third Draft

webtrees guidelines for help text and other translatable strings.

THIRD DRAFT - Developers will discuss and a final draft will be offered in a week.

Readability

Help text should be designed to be readable by a 16-17 year old, measured by a score of 11 or less with the Flesch-Kincaid Grade Level (FKGL) formula or an equivalent rating on a similar model.

When I first became a technical writer, our customer (U.S. Navy) would not accept any text with an FKGL higher than ten. A couple of years later, they changed their standard to eight (about thirteen years old).

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

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.

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

Source files should not contain non-ascii characters. Use the HTML entities instead when creating help text in the base language. Used named entities when they exist; hexadecimal otherwise.

&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

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.

Branding

When naming webtrees, use lower case and bold. If you cannot avoid making it the first word in a sentence, use lower case anyway.

===============
Gratuitous comment by Wes: Sometime prior to SVN 8601, the help text for RESN was rewritten to comply with the above guidelines for Brevity, Whitespace, No fragments, and partially for Markup. Compared to other help texts, it is MUCH easier to translate.

Markup/whitespace. Using this example, would you put the <ul><li> tags in the translation string? If not, how would you construct this?

fisharebest wrote:

Markup/whitespace. Using this example, would you put the <ul><li> tags in the translation string? If not, how would you construct this?

Taking literally “Markup” (which should be revised if it doesn't really reflect what you want), each list item would be a separate i18n call to comply with “Whitespace.” But, this is only an example, and perhaps the principle is overkill for an example that small. For larger examples, it might be a tradeoff between readability for the user and readability/number of separate items for the translator. (And risk of bad HTML due to readability for the writer.)

When I was outputting HTML in other languages, if the language didn't offer them, I would write my own subprograms to guarantee valid syntax. They also helped (very little, but some) with code readability. So instead of typing and balancing the tags over and over, I might say something like The first example that came to mind was probably a bad example. The principle doesn't really apply to lists of single words. I guess I should revise it. Before I do, any other comments?

This forum is so much better than the one on Sourceforge. But, I hate the way it puts code examples into a window half the width of the text with a horizontal scroll bar. Even more, I disapprove of the gratuitous splitting of code lines at a hyphen.

Now back to the real subject, …

WGroleau wrote:

The first example that came to mind was probably a bad example. The principle doesn't really apply to lists of single words.

Agreed.

Also, we should remember is that these are guidelines, not absolute rules.

Also, we should remember is that these are guidelines, not absolute rules.

ABSOLUTELY...