Style guide for software developers

This style guide helps software developers to write clear text on a user interface. This style guide is about the most frequent language problems. This style guide uses British English.

For other style guides, see 'Style guides for software documentation'.

Language guidelines

To give instructions, use statements. Do not use questions or conditions (if …):

Use this:Select the <items> for this <option>.
Do not use this:Which <items> do you want for this <option>?

Use this:Type the number of <items>.
Do not use this:How many <items> are there?

Use this:Choose OK to accept these values.
Do not use this:If you choose OK, these values will be accepted.

To give information and to ask questions use the present tense:

Use this:The <event> starts on <date>.
Do not use this:The <event> will start on <date>.

Use this:Are you sure that you want to delete the <item>?

Keep the text short. If text does not increase clarity, do not use the text (the context is important):

Use this:Select the <item>.
Do not use this:Select the <item> that you want to create.

Use terms that the users understand. If the software is for technical people, then use technical terms. If the software is for non-technical people, then use non-technical terms:

Use this:Type a number between 1 and 10.
Do not use this:Type an integer between 1 and 10.

Be precise:

Use this:Type a number between 1 and 10.
Do not use this:Type a number.

If possible, use parallel structures:

Use this:The <event> starts on <date>. The <event> ends on <date>.
Use this:The <event> start date is <date>. The <event> end date is <date>.
Do not use this:The <event> starts on <date>. The <event> end date is <date>.

Use this:log on / log off
Use this:log in / log out
Do not use this:log in / log off

To show necessity, use must. To show ability use can:

Use this:You must create an <item type> before you can create an <item instance>.

Do not use the words that follow:

Do not use this:could, may, might, should, shall, wish.

Other guidelines

Colour. To give meaning, do not use colour only. Some people are colour-blind.

Images. To give meaning, do not use only images. If a user does not know the meaning of an image, the user cannot understand what to do.

Screen size. Some users do not have high-resolution screens. Do not use very large dialog boxes. Do not use dialog boxes that cannot be re-sized.

Text style. Use italic text and UPPERCASE TEXT carefully. Italic text and UPPERCASE TEXT are both more difficult to read than standard text.

Typeface. Use a typeface that is designed for on-screen viewing, such as Verdana.

See also

Style guides for software documentation

RSS feed

© TechScribe, Sheffield, South Yorkshire. Page created 2010-12-29

  1. Search | A to Z
  2. Services
  3. Resources home page
  4. Writing: style guide
  5. Business development
  6. ISTC online groups
  7. Reviews
  8. Glossary