Wording

1     Use clear writing

• Limit:
  • Sentences to 25 words, or less.
  • Summaries to 160 characters (including spaces), or less.
  • Titles to 65 characters (including spaces), or less.
• Read:
  • Writing for GOV.UK
  • A to Z
  • Words to avoid

2     Gender neutrality

Keep text gender neutral, where possible:

• Good "them", "their", "they"
• Avoid "he", "she", "him", "her", "his"

3     Don't prefix product names with: "the"

Try to avoid prefixing product names with the word "the". E.g.:

• Good "Next download 1st Money for Windows and..."
• Avoid "Next download the 1st Money for Windows and..."

4     Contractions

Use contractions whenever possible. Be informal. Where possible, use: I'm, they're, it'll, we're, you'll, you're, they'll, etc.

• Good "OK"
• Avoid "Okay"
• Avoid "ok"

5     Don't say it's simple

If something's actually simple, you don't need to say it.

Chances are, however, that whatever you're writing isn't simple ... in which case it's better explained without all the "just"s and "simply"s.

• Avoid "All you've got to do is..."
• Avoid "...and then simply click..."
• Avoid "...to see it, just open..."
• Avoid "When you see this, it basically means that..."
• Avoid "...here you can easily see..."
• Avoid "...it's easy to fix."

Read more at: justsimply.dev

6     Hyphens in compound adjectives with numbers

If the word after the number is plural, don't put a dash.

• Good "15-year-old teenager"
• Good "He's 15 years old"
• Avoid "He's 15-years old"
• Good "She's on a five-day working week"
• Avoid "She's working 5-days a week"

7     Abbreviations

Because will be used by speakers of a variety of languages, only use the most frequent abbreviations.

Don't put a period (full stop) after unit abbreviations:

• Good "Tue, Feb, am, pm"
• Good "avg"
• Avoid "avg."
• Good "Wed, Jan 24"
• Avoid "Wed. Jan. 24 th."

Here's some other abbreviations to avoid (although sometimes it's unavoidable due to lack of space):

• Avoid "1 yr"
• Avoid "3 mths"
• Avoid "1 wk"
• Avoid "5 hrs"
• Avoid "12 mins"
• Avoid "1 sec"

Do put periods on latin abbreviations:

• Good "i.e.", "e.g.", "etc."
• Avoid "ie", "eg", "etc"

Ordinal suffixes have no dot, and no space, and are generally only used on dates:

• Good "2nd of May", "3rd quarter", "first try", "third day"
• Avoid "2nd place", "third of May", "2 nd."

8     Numbers

Numbers below 11 should be written as a word, if in a sentence. E.g.:

• Good "ten"
• Avoid "10"

9     Showing keyboard shortcuts

Keyboard shortcuts should be written with:

• No spaces.
• Use the reference to: $Z->ctrlKey

E.g.:

Ctrl+Alt+L

[_<?=$Z->ctrlKey?>_]+[_Alt_]+[_L_]

10     Force keywords and description meta tags

$SharedPage->metaDescriptionText = "Your description here";
$SharedPage->metaKeywordsText = "your, keywords, here";

11     Linking to 1st Money features

Linking directly to 1st Money features helps the customer follow the documentation. E.g.:

• Good "Go to: ProjectPeopleAdd reviewers "
• Avoid "Go to a project then Members menu, then Reviewers."

Code:

<?=\Func\InterfaceLink::build('project', 'reviewers')?>

• The first parameter must be the object type (found in the first part of the URL), e.g.: location, bookmark, project, org, person, etc.
• The second parameter can be found from the last part of the URL or by clicking the three dots beside the form.

12     List items end with a period

All numbered and bullet lists should start with a capital letter, and end with a period (full stop).

• Why? ... When the text from lists gets pushed into 1st Money's support tools, the line breaks and other formatting gets lost.
• By starting each line with a capital, and ending with a period, it helps distinguish each as a distinct item.

13     FAQ names can't include some special characters

The following CAN'T be used in FAQ headings or help file names:

• / or \ (forward slash or backslash).
• $ (dollar).
• £ (pound).
• # (hash).
• ? (question).
• " (double quote).
• & (ampersand).
• * (asterisk).
• {} (curly brackets).
• <> (angle brackets).
• -- (double dash).
• _ (underscore).
• : (colon).
• ^ (caret).
• + (plus).
• | (pipe).
• % (percent).

The following CAN be used:

• ! (exclamation).
• ' (single quote).
• () (normal brackets).
• [] (square brackets).
• - (single dash).
• ; (semicolon).
• @ (at sign).
• ~ (tilde).

14     Other good references

• material.io/design/communication/writing.html

Was this page helpful?