-
Are you referring to the reader and author correctly
in your document?
In technical writing, there are only two valid subjects:
- "You" (the reader)
- The subject (the software, hardware, function etc.)
For example:
- When the CD is inserted, a Windows dialog will be shown.
- Figure: Bad Example - This example does not address the reader or from the point of the subject (the software in this case). It's using a passive voice.
- When you insert a CD, Windows shows a dialog.
- Figure: Good Example - This example does address the reader and is more engaging.
It is occasionally acceptable to use the first person, "we", "I", "us", "our" etc.
An example of an acceptable use of first person is, "We recommend that you
backup your database first." However, you must never use the first person to refer to the reader:
- We will now open a web browser and go to the home page.
- Figure: Bad Example - It is unclear who the "we" is.
- You can now open a web browser and go to the home page.
- Figure: Good Example - These instructions are clear and direct.
-
Do you use the correct symbols when documenting instructions?
An important area which Microsoft does not apply strict standards to, is documenting
instructions. This is often a confusing dilemma for many people, as the way in which
instructions are worded and arranged is very important in helping the user understand
the instructions. Therefore, the instructions should be minimalistic, clear and
concise.
In Ken Getz's words you MUST ALWAYS list the items in the order the user selects
them. I often see on Microsoft documentation: 'Select All Programs from the Start
menu'. That's inexecusable!
- Click Start, then All Programs, then Accessories, then Calculator.
- Figure: Bad Example - No visual cue is given for separate steps
- Start - All Programs - Accessories - Calculator
- Figure: Bad Example - Dashes are easy to glance over
- Start --> All Programs --> Accessories --> Calculator
- Figure: Bad Example - This is better but looks unprofessional
- Start | All Programs | Accessories | Calculator
- Figure: Good Example
SSW Link Auditor to check for this rule. We offer a
rule sample page for demo scan.
-
Do you use the right order of instructions?
When writing the instructions for a series of operations, be sure you keep the operations in the right order. With a clear order, users will be less likely to be confused.
- Select Options from the Tools Menu.
- Figure: Bad Example - These instructions are in reverse and needs to be processed by the user.
- Select Tools | Options
- Figure: Good Example - These instructsion are in order and do not require any effort from the user.
-
Do you highlight items correctly in your document?
When highlighting items (file names, user commands etc.) be sure to:
- Distinguish the items from the rest of the surrounding text; and
- Be consistent.
Use the following rules to highlight items in your document.
|
Style
|
Use this style on
|
Example |
|
Bold text
|
Menus, commands, dialog box options, file names and paths |
To access the application, click Start | Programs | Accessories | System Tools |
Disk Defragmenter |
|
UPPERCASE |
Code keywords and database elements |
Use the INNER JOIN clause in SQL Server to join one table to another. |
|
Initial Capitals + Bold |
File paths and file names |
Now open C:\My Documents\Invoice.doc. |
|
Monospace (Courier New font) |
Code samples, error messages |
You will see the following error: error opening
database: database is currently in use. |
-
Do you make numbers more readable?
Remember to use dividers when quoting phone numbers or large sums.
-
- 2721654230
- Phone: 8583532311
-
Figure: Bad Example - : These number are unweldy and difficult to read
-
- 2,721,654,230
- Phone: (858) 353-2311
-
Good example: A comma, a dash and some spacing makes these large digits easier to
read
-
Do you include version numbers in your file?
It is very important to have your Word, PowerPoint, PDF's and other documents up-to-date and having the version number on the RHS of the footer is the best way to show which version you are looking at.
Please read to understand how you increase the version number:
- Major 1.0 - rarely change - only with major upgrades (e.g. complete redesign)
- Minor 1.1 - new features / release (customer facing) - (e.g. add/remove a heading or a section)
- Revision 1.11 - emergency maintenance, spelling fixes
It is also good practice to include a version number in the name of the file. This helps us to navigate through the old and the new versions. It makes
it easy if we decide to roll back any changes and use an older version.
For example:
-
extreme_email_file
extreme_email_new_file
extreme_email_latest
-
Figure: Bad Example - These files do not show any version information.
-
Extreme_Emails_v1
Extreme_Emails_v2
CodeAuditor_Ver1
CodeAuditor_Ver2
-
Figure: Good Example - These files show the version information.
-
Are you referring to the reader and author consistently throughout your document?
When writing technical documentation, one of your primary objectives is to ensure
the document is written consistently to ensure a flowing reading experience. Ensure
the reader and author are correctly referenced throughout your document, for example:
- When one wants to scan for viruses, you can open the antivirus software.
- Figure: Bad Example - The user is referred in two ways and flow is broken
- When you want to scan for viruses, you can open the antivirus software.
- Figure: Good Example - There is no noticeable break in the reading flow
The first example is bad because it confuses the reader as to whom the author is
referring.
-
Do you add a useful figure caption in bold below all images?
When you add an image to a website or application, follow the Microsoft Word standard
and use "Figure: Description" to describe your images. Read more
about this rule on our Rules to Better Websites - Layout.
-
Do you avoid using unnecessary words?
When writing any documentation it is vital that you avoid using unnecessary words
to keep the reader interested and focussed on the content. This is especially true
in technical documentation, as most of the content is factual.
- Click the "Select" button
- Figure: Bad Example - There are too many unnecessary words
- Click "Select"
- Good Example - This is short and to the point.
It is less wordy, and still gets the message across. Look through your document
now - where else can you get rid of words that don't add any value to the sentence?
-
Do you use "will", not "should"?
When explaining steps in a process, e.g. Printing a file, make sure to say something
"will" happen or is happening. This is especially important when describing
your own software, because saying something "should" happen implies that
it may or may not happen, i.e. there could be bugs!
-
To print your document:
- Select File | Print. The Print dialog should now show.
- Select the number of copies and click Print. The file should now print.
- Figure: Bad Example - Using "should" implies uncertainty
-
To print your document:
- Select File | Print. The Print dialog is shown.
- Select the number of copies and click Print. The file will now print.
- Good example - Using present or future tense implies confidence
SSW Code Auditor because it picks up false positives.
-
Do you use 'setup' and 'set up' correctly?
Often when writing technical documents, you will instruct the reader to 'set up' his PC or run a 'setup' file. Remember that 'set up' is a verb, and 'setup' is a noun.
- Verify that your network setup is correct before attempting to connect to the Internet.
- Figure: Good Example - This is the correct use of "setup"
- Click Go to set up your database.
- Figure: Good Example - This is the correct use of "set up"
'Set up' is a verb with many meanings, most commonly 'to establish something.' 'He is going to set up shop.'
The single word 'setup' is a noun, basically meaning an 'arrangement.' 'The setup was all wrong.'
How can you remember this? Mentally replace 'setup' or 'set up' with 'setting up.' If the sentence still basically
makes sense, use two words. If it doesn't, use the single word. For example, the
sentence 'he is setting up shop' makes sense. 'The setting up was all wrong' does not.
-
Do you know email should be email without the hyphen?
Microsoft Word spell checker is lenient about 'email' versus 'e-mail', but you should use 'email' instead.
What if you wanted to say "Re-email this report please"... surely you would not say "Re-e-mail this report."
SSW Code Auditor to check for this rule.
-
Do you know commas and full stops always should have "one" space after it?
When writing any documentation it is important to put only "one"
space after commas or other punctuation. This makes the document easy to read and
looks more professional.
For example:
-
Looking for your sent emails through a searching tool is simple.By using Windows
Desktop search,you can search your relevant emails by recipient and/or by subject.
- Figure: Bad Example - No space after comma and full stop
-
Looking for your sent emails through a searching tool is simple. By using
Windows Desktop search, you can search your relevant emails by recipient
and/or by subject.
- Figure: Bad Example - Two spaces after comma and full stop
-
Looking for your sent emails through a searching tool is simple. By using Windows
Desktop search, you can search your relevant emails by recipient and/or by subject.
- Figure: Good Example - One space after full stop and comma
-
Do you use quotation mark for controls?
Quotation mark can help user distinguish controls from the normal words. This is especially important
in technical documentation, as the control names can be normal words.
- Click the Upgrade link
- Figure: Bad Example - It's not clear that Upgrade is a control
- Click the "Upgrade" link
- Figure: Good Example - This is much clearer to the user what to search for.
-
Do you show examples, a "bad example", then a "good example"?
Always show the bad example first, then good example like below:
-
To print your document:
- Select File | Print. The Print dialog should now show.
- Select the number of copies and click Print . The file will now print.
- Figure: Bad Example - Using 'should' implies uncertainty
-
- Select File | Print. The Print dialog is shown.
- Select the number of copies and click Print. The file will now print.
- Good example - Using present or future tense implies confidence
Note: Images with Balloons might be better in this case.
-
Do you know how to add quotations?
When you add a quotation, put them in a new line with an indent.
-
Software development can be painful and costly. Hang on, that should say "Software development IS painful and costly."
- Figure: Bad Example - The quotation without a new line or indent
-
Software development can be painful and costly. Hang on, that should say:
"Software development IS painful and costly."
- Figure: Good example - The quotation on a new line and indenting
You should always indent any quotes that you use on a new line.
-
- Figure: Bad example, it is hard to tell where the quote is
-
- Figure: Good example, it is obvious that this is a quote and it is laid out nicely.
Tip: In Windows Live Writer there is a button for this:
-
- Figure: Use the Quote button in Windows Live Writer
This wraps your text in a <blockquote> HTML element. This lets you display it any way you like on a web page.
-
Do you know when to use log on, log in, and sign in?
In order to connect (with a username and password) to:
- a Winforms application, you "log in"
- a Webforms application, you "sign in"
- a PC, Server or Domain, you "log on"
-
Would you like to logon to your new account?
Would you like to log-on to your new account?
Would you like to login to your new account?
Would you like to log-in to your new account?
Would you like to signin to your new account?
Would you like to sign-in to your new account?
- Figure: Bad examples
-
Would you like to log in to your timesheeting application?
- Figure: Good example - Winform
-
Would you like to sign in to your email account?
- Figure: Good example - Webform
-
Would you like to log on to your computer?
- Figure: Good example - PC, Server or Domain
See the Login From Wikipedia.
SSW Code Auditor to check for this rule.
-
Do you use "cannot" and "website" instead of separated words?
Grammatically, all of them are acceptable spellings, but in these specific cases, one word is more usual. Refer to AskOxford for reference.
Note: When there are two ways of doing something, we make a rule on it one way with the goal of having complete consistency.
-
You can not change the world.
- Figure: Bad examples – two separated words
-
You cannot change the world.
- Figure: Good example - using these terms in one word
SSW Code Auditor to check for this rule.
-
Text - Do you use "Taskbar" instead of "Task Bar"?
- Figure: Good Example - You should use the "taskbar" over "task bar"
-
Text - Do you use "Try Again" instead of "Retry"?
They are similar but "Retry" is a more computer jargon like.
- Figure: Internet Explorer uses "Try Again" instead of "Retry"
-
Spelling - Do you use Microsoft Word's spelling and grammar checker to double check your content is professional?
Improper spelling, grammar and punctuation in your content give a bad impression of your company. It is unprofessional so always use Microsoft Word's 'Spelling & Grammar' checker prior to saying 'done'. Bottom line aim to say 'done and spell checked'.
If it is web content you need an extra step. So Copy and Paste it to MS Word then press F7 (or on the ribbon go to Review > Spelling & Grammar) to check your text
- Figure: Click on "Spelling & Grammar" button to check your web content.
Please read the related rule here - Are you careful with your spelling, grammar and punctuation?
-
Do you use words instead of digits for low numbers?
Whenever writing numbers for a web audience, it's generally a good idea to use numerals, especially for complicated numbers. Numerals are more easily noticed when a page is scanned by a user's eye.
- There are seventy three good reasons to do this.
- Figure: Bad Example - The number is spelled out.
- There are 73 good reasons to do this.
- Figure: Good Example - This is easy to read and more noticeable
The exception is generally very small numbers (one and two) which are normally spelled out.
- 2 heads are better than 1.
- Figure: Bad Example - Numerals used
- Two heads are better than one
- Figure: Good Example - Numbers are spelled out
-
Do You Know How to Capitalize a Title?
It is important to use correct Capitalization when writing titles/headings for things.
- "the Man in the Moon owns a yellow Balloon"
- Figure: Bad Example – The first letter of the first and last words should always be capitalized
- "The Man in the Moon Owns a Yellow Balloon"
- Figure: Good Example – Only conjunctions, prepositions and words that should be lower case for another reason should not be capitalized.
For more information go to Writer's Block - Writing Tips - Capitalization in Titles.