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 posted in a week.

Readability

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

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 (as judged by those formulas) has a readability of about 17 years old. These guidelines show about twelve years old. Psalm 119 (New International Version) scores equivalent to about eight years old.

If you choose to use a formula, the following will give more info about them and even measure text for you. Microsoft Word can also compute FKGL.

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 subjective. 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.

Some possible guidelines:

[il]If it can’t fit on a 800x600 screen and still be easy to read, it should be in the Wiki.[/li][il]If it is as big as RESN_help, it should be in the Wiki.[/li]
• If it is big enough to need a lot of HTML tags, it should be in the 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 sufficient 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:
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, and a preface to another genealogy website.

Better:
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.

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.