-
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.
-
When you insert a CD, Windows shows a dialog.
The first example is bad because it is not addressing the reader or writing from
the point of the subject (the software in this case), ie. using the passive voice.
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.
-
You can now open a web browser and go to the home page.
The first example is bad because it is unclear to the reader as to who "we" is.
-
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 Getzs words you MUST ALWAYS list the items in the order the user selects
them. I often see Microsoft documentation say: 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
We have a program called 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 of the right order
of them. With the clear order of operations, users won't be confused anymore.
Select Options from the Tools Menu.
-
Figure: Bad Example - See how it is in a reversed menu order than the one the user
will do it in.
Select Tools | Options
-
Figure: Good Example
-
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 include version numbers in your file names?
It is a good practice to include a version number in the name of the file. Every
time you make a significant change to the file you should increment the version
number. 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
-
Bad file naming conventions :
- Extreme_Emails_v1
- Extreme_Emails_v2
- CodeAuditor_Ver1
- CodeAuditor_Ver2
-
Good file naming conventions :
-
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.
-
When you want to scan for viruses, you can open the antivirus software.
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
-
Bad Example
-
Click "Select"
-
Good Example
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"?(CANCELLED BY ADAM)
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 will now show.
- Select the number of copies and click Print . The file will now
print.
-
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
-
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.
Correct use of "setup": Verify that
your network setup is correct before attempting to connect to the Internet.
Correct use of "set up": Click Go to set up your database
"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 settingup was
all wrong" does not.
-
Do you know email should be email without the hyphen?
Yes Microsoft Word spell checker is wrong.
Good - "email"
Bad - "e-mail"
I do prefer to see email as email as the hyphen is really an extra thing that serves
no purpose anymore.
What if you wanted to say "Re-email this report please"... surely you would not say "Re-e-mail this report"... sounds like you have a stutter.
-
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.
-
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.
-
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.
-
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 controls' name are normal words.
-
Click the Upgrade link
-
Bad Example
-
Click the "Upgrade" link
-
Good Example
-
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
will now show.
- Select the number of copies and click Print . The file will now
print.
-
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
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 4 spaces (indent).
-
Software development can be painful and costly. Hang on, that should say "Software development IS painful and costly."
-
Bad example - The quotation without a new line with 4 spaces
-
Software development can be painful and costly. Hang on, that should say
"Software development IS painful and costly."
-
Good example - The quotation with a new line and 4 spaces
-
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.
We have a program called
SSW Code Auditor to check for this rule.
-
Do you use "cannot" instead of "can not"?
When we check spelling in MS Word, it will suggest changing "can not" to "cannot".
According to AskOxford, both "cannot" and "can not" are acceptable spellings,
but the first is more usual.
At SSW, when there are 2 ways of doing something,
we make a rule to do it one way with the goal of having complete consistency.
-
You can not change the world.
- Figure: Bad examples - using "can not"
-
You cannot change the world.
- Figure: Good example - using "cannot"
We have a program called
SSW Code Auditor to check for this rule.
-
Do you know to indent quotes?
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.
-
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?