Question Help Text Guidelines - First draft

A day late and how many dollars short?

Rip it apart, folks—what did I leave out and what did I get wrong?

webtrees guidelines for help text and other translatable strings.

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


Readability

Help text should be written at an eleventh grade level or easier.

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 for grade level. This draft of the guidelines is about a seventh-grade level. Psalm 119 (New International Version) is about third-grade level.

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 FAQ, Wiki, or other source.

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.

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

I have no problems with any of that, in fact its an excellent plan. Thanks Wes. I only think we need to make sure, in your long thread, that everyone's attention is drawn to, IMHO, the most important change proposed:

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 FAQ, Wiki, or other source.

I would exclude FAQ from this, as the FAQ system in webtrees (and PGV for that matter) is user/site configurable, not controlled by us. The WIKI is the only solution. Whatever is entered in the Help pop-up should, I believe, fit within the pop-up without causing any need for scrolling. In most cases this therefore only applies to the long "Help for this page" type texts.

Also, once agreed, we should include this guideline prominently on the WIKI, as it's recommendations about writing style apply equally well there. Perhaps even more so, as those texts will always be longer. I do recommend the use there of images as often as practical - "A picture is worth a thousand words".

Rip it apart, folks—what did I leave out and what did I get wrong?

If someone has a specific question for me, I’ll try to answer. Otherwise, I am going to just lurk and let the developers agree or disagree with each other. Then next weekend, edit the second draft based on their discussion.

"View readme.html file"
Is that a candidate for the Wiki approach you're promoting?

(so much for lurking)

Not really, although similar. The readme.html file is included in the webtrees "package" (used to be readme.txt in PGV) as a guide people can read BEFORE installation. It was very long, and as a pure text file, hard to read (no bookmark links, highlighting etc etc. So I am re-writing it as a basic html page that anyone can open in a browser, even if not connected to the internet. However, at the same time I have ensured it is identical to a "ReadMe" set of pages on the WIKI.

What you have referred to is a link from the Admin page to the local file. Its not a pop-up, so not limited to any window size issues, and its format is very simple, so no issues with browser compatibility, screen width etc. Not the sort of issues we have with Help text. Probably the real question is whether that link needs to exist at all. Its just a left over, whose use hasn't been discussed.

1) Since I needed to google this: "eleventh grade" means a 15 year old.

2) "± %d years " is easier to read than "&plusmn; %d years"

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; and &lt;. This is no different.