-
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
-
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 whether login or log in or log on is correct?
The act of connecting (with a username and password) to a PC, server, or Web site is referred to as "login".
-
Can you try to log on to your new account?
Can you try to log-on to your new account?
Can you try to log-in to your new account?
- Figure: Bad example
-
- Figure: Bad example - Log On
-
- Figure: Bad example - Log On
-
Can you try to logon to your new account?
Can you try to login to your new account?
- Good example
-
- Good example - Logon Credentials
See the Login From Wikipedia.
We have a program called
SSW Code Auditor to check for this rule.