Style guidelines
Grammar, spelling, and mechanics aspects of Wire editorial style.
- Abbreviations
- Articles
- Capitalization
- Numbers
- Politeness
- Punctuation
- Typography
- Word choice
- Reference resources
Abbreviations
Avoid abbreviations where possible. Use “for example” instead of “e.g.” or “that is” instead of “i.e.” or — better yet — edit to avoid these constructs entirely.
Articles
Avoid articles in UI copy whenever possible. Articles include “a”, “an”, “the”, etc. Also avoid demonstrative words such as “this” and “those”.
Capitalization
Use all caps for system messages (“UNBLOCK”) in the conversation view and in certain other places as necessary to agree with (Android) platform conventions.
However, for longer phrases or sentences, use sentence case: only capitalize the first word of a phrase or sentence (“You’ve left this conversation”).
Headings on the website, support site, and longer documents should use case consistently (either sentence case or title case) based on context.
For example, CS content at support.wire.com uses sentence case in the question list, but title case in page headings (as required by the Zendesk customer service platform). Certain channels (such as press releases) may have other conventions. Respect these wherever possible.
Use sentence case for headings in long-form documents, as this is a better match for our “humble and friendly” voice. Some perceive title case as more formal and a bit too stiff for our tone, so avoid it in contexts where it’s not required.
In UI copy, capitalize according to the platform conventions, such as Apple’s conventions from the Human Interface Guidelines for iOS and macOS.
As a general rule, menu commands use title case on Apple platforms, but checkboxes and radio buttons use sentence case. See Use the Right Capitalization Style in Labels and Text.
This is one area where Android Writing Style differs:
Use sentence-style caps for all titles, headings, labels, menu items
Numbers
In the application, numerals should be used in all cases to save space:
- 1 message pending
- 3 conversations
- Your password must be at least 6 characters
However, on the website, numbers from one to nine should be spelled out.
For example: “there are three ways to download Wire.”
Treat ordinal numbers the same way: spell out first to ninth, and use numerals for anything 10th or greater. One common case is “third-party licenses.”
Politeness
Be courteous, not patronizing or obsequious. Use “please” or “thank you” where applicable, but use these phrases judiciously.
For example, in an initial message in the app, Wire might ask a user to “Enter a phone number”. If there’s a mistake and a second message is necessary, this is the time to say: “Please enter a valid phone number”.
Punctuation
For complete punctuation rules, refer to standard American style guides. Consider these key points and exceptions:
- Do not use periods in UI strings unless there are two or more sentences.
For example: “Start a conversation”. However, copy on the website should be punctuated correctly. - Use the serial (or “Oxford”) comma in a list of three or more items.
For example: “email, phone number, and address”. - Avoid apostrophes, exclamation marks, ampersands, slashes, and the “+” symbol in UI copy wherever possible.
- Use “logical punctuation” for clarity: place the second member of a pair of quotation marks before any other adjacent mark of punctuation, unless the other mark is part of the quote. Note: This differs from default American style.
Typography
Most UI strings files are now UTF-8 encoded, so typographically correct characters can be used in most cases — there’s no excuse for substituting ASCII text where proper typography is available.
Use “curly quotes”, em- and en- dashes (–/–), ellipses (…), and other proper typographic characters wherever possible.
-
To offset phrases (like in the sentence above), press
⌥ + ⇧ + -on a Mac to insert the longer em dash (—) and add a space on both sides of the dash. -
To indicate a range of numbers, press
⌥ + -on a Mac to insert an en dash (–) with no space between the dash and numbers. -
Never use three dots (. . .) when you need an ellipsis. Press
⌥ + ;on a Mac to insert the proper ellipsis (…) character.
Word choice
Whenever possible, cut unnecessary words. Avoid using too many qualifiers (adjectives, adverbs), modifying clauses and jargon.
Be careful that you don’t bury the action of your sentence in a noun. Instead, take the action out of the noun and put it in the verb format.
Reference resources
In addition to the platform-specific resources described under UI copy, the following resources provide useful reference.
For guidance on Apple-specific terminology, the writer should refer to the Apple Style Guide. That document covers style and usage issues, and is the key reference for how Apple uses language.
For complete punctuation rules and other writing conventions, refer to these style guides: