Principles
Here are some principles of technical writing we have learnt over the years, to which we strive to adhere. The examples show the application of each principle.
- Accuracy
- Get the facts right, then write accurately.
- Clarity
- Explain the topic clearly, paying particular attention to any vocabulary specific to the topic.
- Brevity
- The more words, the less meaning, and how does
that profit anyone?
- Standards
- Define and publish standards for page layout, character formatting, terms, spelling, syntax and everything else that affects document quality. Adhere to all corporate standards for colours, logos and fonts.
- Consistency
- Apply all standards consistently.
- Example 1, standard syntax defined as:
Click the button to open/close the window.
| Right |
Click the OK button to open the BigApp window. |
| Wrong |
When you hit the OK button the BigApp screen displays.
Clicking Ok invokes the BigApp window.
The BigApp window is shown after you click OK. |
- Example 2, character formatting standard for menu names defined as case sensitive bold.
| Right |
Select Set Threshold from the Alarm menu. |
| Wrong |
Select Set threshold from the Alarm menu.
Select Set threshold from the Alarm menu.
|
- Objectivity
- Do not personify a product.
| Right |
The scanner resolution is automatically set to match the target frequency. |
| Wrong |
BigApp automatically sets the scanner resolution to match the target frequency. |
- Correspondence
- Use exactly the same text to describe a screen feature or example.
- Example 1, window titled BigApp Data Window.
| Right |
Close the BigApp Data Window. |
| Wrong |
Close the BigApp data window.
Close the data window. |
- Example 2, field displays
Brian Smith.
| Right |
Type your name, e.g. Brian Smith |
| Wrong |
Type your name, e.g. Sue Jones
Type your <Firstname Lastname> |
- Examples
- Use consistent, relevant examples to explain your subject, using the same details throughout the text where possible. If a document describes how to create, edit, and delete a customer record, describe these procedures in the order in which they are normally performed, using the same customer details in each case.
- Active Voice
- Use the active voice when writing instructions. Do not use the passive or conditional voice.
| Right |
Click the OK button to open the BigApp Data window. |
| Wrong |
Clicking the OK button opens the BigApp Data window.
If you click the OK button the BigApp Data window opens. |
- Chunking
- Group related information using subheadings, lists and tables. Break up long blocks of text, especially in on-line documents.
- White Space
- Use enough white space to separate page elements without overly limiting the amount of information that can be displayed on a page. Very large margins, indents and heading spacings just waste useful space and can increase printing costs.