Writing Goals & Principles
Text and visual components support each other to provide a good user experience of a product. Given that most users don’t have the time to read ( web users read at most 28% of the words during an average visit) and that scanning is a more common behavior, as product designers we need to ensure that every word counts.
There are four basic principles in effective UX writing:
- Clear: use simple language and simple sentence structures. Do not overcomplicate the core message. Do not use jargon or discriminatory language.
- Concise: make sure the copy is meaningful, laconic, and focused on the goal. Avoid redundancy, deadwood phrases, phrasal verbs, and using too many modifiers.
- Useful: the copy needs to provide users with necessary information and help them with interactions.
- Consistent: retain the same style, tone, voice, and terminology within the product.
Understanding Users
To write content that helps users perform specific tasks, you must know who the users are and what they want to do. Make sure the language you use in your product is familiar to the user: use words, phrases, and concepts the user can easily understand. Before starting to write, make sure you can answer the following questions:
- Who are the users?
- What do they know?
- How are they going to use the information?
- What questions will they ask?
When writing content for your product also consider the different cognitive or reading styles. For example, some readers are more comfortable with text, others with graphics. Many readers need a combination of the two.
Organizing Information
Once you know who the users are and what they want to do, you can start to organize content logically and in a way that users will recognize. Good organization helps users to navigate through the software easily, without creating excessive cognitive load.
Writing Style Guide
The following writing style guide was first developed in 1997 to ensure consistency across all the publications we were developing for various products.
Our main references are:
For detailed information on Trimble voice, tone, style and writing style guidelines for creating editorial content, please refer to the Trimble Editorial Guidelines which can also be accessed through the Trimble Marketing and Sales Collateral.
Abbreviations
An abbreviation is a shortened form of a word, created by omitting some of its letters. An abbreviation is formed in several ways:
- Shortening the word, e.g., altitude (alt)
- Using the first letter of each word in a phrase, e.g., Liquid Crystal Display (LCD)
- Using significant parts of words in a phrase, e.g., Receiver INdependent EXchange Format (RINEX)
Abbreviations can save space and make text easier to read.
- Use abbreviations only if they are common, or if you are certain that your readers will understand them easily.
- Spell out the term the first time it is used, and enclose the abbreviation in parentheses after it. Thereafter, use the abbreviation alone.
- When an abbreviation follows an indefinite article, the choice of “a” or “an” is determined by the way the abbreviation would be read aloud, e.g., “an SVD file”.
- Use recognized abbreviations. Do not make up your own.
Latin abbreviations:
Use Latin abbreviations sparingly in text. Whenever possible, use the English equivalents:
- i.e. (id est) = that is
- e.g. (exempli gratia) = for example
- etc. (et cetera) = and so forth
If you have to use Latin abbreviations due to limited space (as in a table), use the appropriate punctuation, that is, a comma before and after.
Ampersand
Do not use ampersand in regular or paragraph text as a replacement for and. You may use ampersand in titles, navigation, or tables to save space.
Capitalizations
Capitalize proper nouns, specific geographical regions, headings, composition titles, first word of a document, and the first word after a period. Avoid using all uppercase.
Use title case for page titles, modal/ dialog titles, menu/ navigation items, and form field labels. When using title case,
- Capitalize the title’s first and last word.
- Capitalize all adjectives, adverbs, and nouns.
- Capitalize all pronouns (including it).
- Capitalize all verbs, including the verb to be in all forms (is, are, was, has been, etc.).
- Capitalize no, not, and the interjection O (Example: How Long Must I Wait, O Lord?).
- Do not capitalize an article (a, an, the) unless it is first or last in the title.
- Do not capitalize a coordinating conjunction (and, or, nor, but, for, yet, so) unless it is first or last in the title.
- Do not capitalize the word to, with or without an infinitive, unless it is first or last in the title.
- Do not capitalize a preposition, unless it is first or last in the title.
Use sentence case for lower level headings, figure captions and table titles, callouts, button labels, and body copy.
Colons
A colon follows a word, phrase, or sentence to introduce a series of items that follows.
Example:
The information in this report includes the following:
- LP synchronization mode
- Scheduling parameter value
Use a colon to separate elements in a title or heading (Example: Trimble Software: Updating).
Do not use a colon if a preposition or a verb precedes the series (Example: The three choices are cut, paste, and copy).
When a colon is used within a sentence, the first word following the colon is lowercase unless it is a proper noun. When a colon introduces two or more sentences, or when it introduces speech in a dialogue or an extract, the first word following it is capitalized.
Commas
- Use a comma to separate introductory phrases or clauses from the rest of the sentence.
- Use a comma between independent clauses that are joined by a conjunction and have separate subjects Do not use a comma before a conjunction in a compound sentence where two verbs have the same subject.
- When listing three or more elements, use the “Oxford comma” (also called “serial comma”) to prevent ambiguity.
- Nonrestrictive clauses are not essential to the sentence’s meaning. Use a comma before a nonrestrictive clause, introduced by the word which. Use a second comma if the clause does not end the sentence.
- Restrictive clauses are essential to the sentence’s meaning. Do not use a comma before a restrictive clause introduced by the word that.
Compound words
Compound words are two or more words joined to express a single idea. There are three types of compound words:
Open (e.g., ice cream): use with
- compound adjectives formed with an adverb ending in -ly and a participle (Example: poorly organized plan)
- compounds formed from a verb ending in -ing and its object (Examples: problem solving, batch processing)
Closed (e.g., flowchart): use with
- most compound nouns formed with out, off, down, or up (Examples: backup, readout)
- most compound words formed with prefixes or suffices (Examples: prerequisite, backward)
- some short compound words that become common through use (Examples: worksheet, trademark)
- most compound words that end in book, keeper, light, making, power, proof, room, shop, time, ware, wide, work (Examples: workshop, waterproof).
Hyphenated (e.g., left-hand): use with
- compound verbs that consist of an adverbial noun and the modified verb, prepositional phrase used as an adjective (Examples: to field-test, to machine-process)
- prepositional phrase used as an adjective (Examples: up-to-date information, out-of-range marker)
- fractions written out and used as modifiers (Example: one-half inch)
- numbers plus the unit of measurement, when modifying a noun (Examples: 50-Hz transformer, 16-bit timer)
- compound adjectives that consist of an adjective and a past participle (Examples: odd-numbered pages, right-justified columns)
- compound adjectives that consist of the past participle of a verb followed y an adverbial preposition (Example: worn-out condition)
- compound nouns that have different, but equally important functions (Example: transmitter-receiver)
- most temporary compounds ending with in, when modifying a noun (Examples: built-in module, tie-in strap)
If a compound word has become commonly used, the trend is to use closed spelling. For example, stand-alone has become standalone.
Currency
Use the International Standard:
- USD: United States dollar
- NZD: New Zealand dollar
- GBP: British pound
- EUR: Euro
Leave a space between the currency abbreviation and the value, e.g. NZD 100.
Dashes
En dash (–): use in a range of numbers, to represent the word to and as a minus sign in text or equations.
Em dash (—): use to interrupt a sentence, add new or unfinished information, or emphasize parenthetical expressions.
Dates
Generally, spell out the day of the week and the month. Abbreviate only if space is an issue.
- Saturday, January 24
- Sat., Jan. 24
The simplest way to write dates that can be understood by anyone in the world is to write the month portion of the date in words instead of numbers.
- Write “August 5, 2020” or “5 August 2020” instead of “8.5.2020” or “5.8.2020.”
- It doesn’t matter if the day comes first (“5 August 2020”) or after (“August 5, 2020”). Use whichever arrangement you’re most familiar with in your country.
Avoid st, nd, rd, th (as in 1st, 2nd, 3rd, 4th)
Use a hyphen (-) to indicate a range of yours, and always write the full year.
- Write “2015-2016” (not “2015-16” or “2015 to 2016”)
Ellipses
An ellipsis is a series of dots that usually indicates an intentional omission of a word or section from a text without altering its original meaning.
- Use three points of ellipses (periods), without spacing before or after, to indicate an omission within a sentence, at the beginning or end of a sentence, or in two or more consecutive sentences.
- Use the correct special character symbol to insert an ellipse rather than typing a period three times.
- If an ellipsis occurs at the end of a sentence, insert a space before the ellipsis and keep the period at the end of the sentence.
Lists
Bulleted lists:
- Complete sentences require periods.
- Incomplete sentences or phrases do not require periods.
- If a list contains one item that requires a period, then end all items in the list with a period.
- Begin the first word in an item with a capital letter unless the list items continue the stem sentence.
- If possible, begin each list item with the same part of speech.
Numbered lists: use numbered lists for steps in procedures or when you want to emphasize a sequence. Do not use a 1 without a 2 or an a without a b.
Parenthesis
Parentheses (or brackets) enclose words, phrases, or sentences to add clarity to a statement without altering its meaning. Parentheses make the inserted element or text seem less important than the rest of the text.
- Parenthetical information may not be essential to a sentence, but it may be interesting or helpful to some readers.
- Parenthetical material does not affect the punctuation of a sentence. If a parenthesis closes a sentence, the ending punctuation appears after the parenthesis. Also, a comma following a parenthetical word, phrase, or clause appears outside the closing parenthesis.
- However, when a complete sentence within parentheses stands independently, the ending punctuation goes inside the final parenthesis.
Quotation marks
Quotation marks (” ”) are used in technical manuals only as parts of commands, statements, or character sets.
When quotation marks are at the end of a sentence:
- Place commas and periods inside end quotation marks.
- Place question marks inside quotation marks if they are part of the enclosed material. However, if the enclosed material does not contain a question, but the main sentence is a question, place the question mark outside the quotation mark.
- Place a colon or semicolon outside an end quotation mark.
Semicolon
Use a semicolon:
- To join independent clauses that are not joined by a comma or a conjunction (Example: No-one applied for the position; the job was too difficult).
- In compound sentences, before transitional words or phrases (that is, for example) that introduce an independent clause (Example: The study group was aware of his position on the issue; that is, he was not going to complete the job).
- Before conjunctive adverbs (therefore, consequently, furthermore, however, otherwise) that connect independent clauses (Example: I won’t finish today; therefore, I doubt that I will finish this week).
- Between two main clauses connected by a coordinating conjunction (for, and, nor, but, or, yet, so) if the clauses are long and contain other punctuation (Example: The system contains various components, both subsystems (a through d) and individual units (1 through 10); but all components interact independently).
- If items in a series contain commas within them (Example: Among those present were John Howard, president of Omega Paper Company; Carol Martin, president of Alpha Corporation; and Larry Stanley, president of Stanley Papers).