Design/Guidelines/UIWriting

    From The Document Foundation Wiki

    TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate

    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 declarative sentences with a period. If your UI copy consists only of a sentence fragment (e.g., if a tooltip only consists of a tool’s name),[2] then do not 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.
    Warning.svg

    Capitalization guidelines for other languages
    Languages other than English may have different rules about capitalization. For example, Swedish and Spanish have no concept of Title capitalization, and German capitalizes every noun, regardless of its position.
    Contact a language translation team if you are in doubt about how to capitalize labels in a particular language.

    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 Legacy Preferred 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 (contrary to what Apple and GNOME typography guidelines might imply): 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 at the time were available under the CC BY-SA 4.0 license.
    Retrieved from "https://wiki.documentfoundation.org/index.php?title=Design/Guidelines/UIWriting&oldid=579080"