Design/Guidelines/UIWriting

From The Document Foundation Wiki
Jump to: navigation, search

Use this guide when writing English UI copy and help content for LibreOffice.

Language considerations

Dialect

Source strings should be written with the US spelling (-ize rather than -ise, et cetera).[note 1] We have British English translators who provide localization for the European variant.

Punctuation

Hyphenate prepositive compound adjectives:[1] well-known procedure, but This procedure is well known. When pairing an adverb ending in -ly, there is no need to hyphenate (finely-tuned is inappropriate).

End complete sentences with a period. If your UI copy consists only of a sentence fragment (e.g., a short tooltip),[2] then don’t add a period.

Capitalization

Two styles are used in UI copy: sentence case and title case.[3]

Title case

It is used for:

  • Headers and headings; i.e., window and section titles.
  • Push widgets and command names; i.e, menus and buttons.

In this style, one makes an exception for articles, coordinating conjunctions and short prepositions.[4]

Sentence case

It is used for:

  • Tooltips and in-dialog descriptions
  • Labels: check boxes and radio buttons.

Get it right the first time you introduce a string. As most languages only ever use sentence case, it’s annoying having to retranslate a string because its capitalization was non-compliant the first time around.

Contractions

Avoid them. They strike as too casual for our tone of voice,[5] and may hinder understanding for non-native speakers.[6]

Typography

Historical computing limitations (there was a time before Unicode existed when you couldn’t write a multilingual document!) and questionable US-centric design choices for keyboard layouts (I’m looking at you, IBM!) have taught our generation that a quotation mark or a prime should be written as: ". In fact, in the history of the written language, this character is very, very recent—it’s only a remnant from the times where typewriters had a limited amount of keys, so symbols had to be spared. Even worse, for my native language, there were many typewriters that didn’t include the figure “1” because it could be simulated by a lowercase “l”. Would you write ells instead of ones today? I don’t think so. So why do you still provide UI copy like we are in the ’80s?

Leveraging Unicode is not only good for precision, if you care about semantics. Taking care of UI microtypography also gives our application professionalism—it shows that we care about our product, and signals users that they, too, can create such polished documents with our application. And if there is a technical limitation preventing us from taking advantage of Unicode, then that is a bug that should be fixed.

Unicode replacements for commonly overloaded ASCII characters[note 2][7]
Usage Incorrect Correct Unicode to use
Quotation "Quote" “Quote” U+201C and U+201D[note 3]
Inches 1.25" 1.25″ U+2033
Ratios[note 4] 16:9 16∶9 U+2236
Arithmetic 1366 x 768
-2.54 cm
1366 × 768
−2.54 cm
U+00D7
U+2212
Ellipsis Cell Style... Cell Style… U+2026[note 5]
Sentence breaks
and parentheticals
LO is evergreen -- it updates
every six months
LO is evergreen—it updates
every six months
U+2014
Apostrophe What's New? What’s New? U+2019
Unordered lists - Item
- Item
- Item
• Item
• Item
• Item
U+2022
Ranges 5-10 minutes 5–10 minutes U+2013
Menu sequences File > Properties File ▸ Properties U+25B8[note 6]

Notes

  1. Some common differences between both dialects are described in the Canonical documentation style guide.
  2. …To use the term the Unicode Consortium itself uses: For historical reasons, U+0027 is a particularly overloaded character […].
  3. Other languages and locales use other quotation marks or place them differently.
  4. Time is not a ratio, so using “:”, as mandated by ISO 8601, is okay: 3:20 p.m.
  5. While this character is the correct way to denote an ellipsis in languages using the Latin, Greek and Cyrillic writing systems, it should instead be replaced with “...” for logographic languages, because the dedicated code point is often placed not on the baseline, but set in the middle of the line, due to historical reasons. This change is responsibility of the relevant localization teams.
  6. For languages written right-to-left, U+25C2 ◂

References

  1. “Hyphens”: Punctuation rules, grammarbook.com.
  2. See “Help tags” in Apple’s HIG.
  3. “Capitalization”. elementary Human Interface Guidelines.
  4. “Title capitalization”. KDE Human Interface Guidelines.
  5. “No contractions”. OpenOffice.org User Interface Text Style Guide.
  6. “Contractions”. KDE Human Interface Guidelines.
  7. This table is modified from GNOME’s typography guidelines, which are available under the CC BY-SA 4.0 license.