Rules to Better Technical Documentation

​​

Hold on a second! How would you like to view this content?
Just the title! A brief blurb! Gimme everything!
  1. Do you show a "bad example" and then a "good example"?

    Always show the bad example first, then good example like below:

    To print your document:
    1. Select File | Print. The Print dialog should now show.
    2. Select the number of copies and click Print . The file will now print.

    Figure: Bad Example - Using 'should' implies uncertainty

    To print your document:​
    1. Select File | Print. The Print dialog is shown.
    2. Select the number of copies and click Print. The file will now print.

    Good example - Using present or future tense implies confidence

  2. Web content like wikipedia/instructional style - Do you write in the newsreader and eyewitness style?

    ​General web content should always be written as if read by a newsreader. It is objective and describes its content professionally. A good example of this is Wikipedia.​​

    I don't like JavaScript. I prefer jQuery because...

    Figure: Bad Example - using 1st person writing makes it sound like opinion

    jQuery is superior to JavaScript for this because...

    Figure: Good Example - using 3rd person writing makes it sound like fact

    However, when quoting a testimonial, you should use 1st person writing as if a newsreader had crossed over to an eye​witness for a personal view of the topic.

    Don Bradman thought that SSW's work was fantastic!

    Figure: Bad Example - impersonal

    Don Bradman says: "I thought that SSW's work was fantastic!"

    Figure: Good Example - 1st person in this context is appropriate
    ​​
  3. Do you know to capitalize tech terms correctly?

    ​​​​With so many different capitalization conventions used in technology names, it can be confusing to know which convention to use for which technology. 

    John Bristowe tweeted corrections for some commonly mis-capitalised tech names

    Figure: John Bristowe tackled some of the most commonly confused tech names in this tweet​​
    Figure: bad example. If you want to be taken seriously as an expert in the subject, you should properly and consistently spell, punctuate, and capitalize the technology you are working with. ​​​​


    Good example: This banner shows the correct capitalization for .NET

    Figure: good example – the technology is consistently capitalized correctly across the page​​​
  4. 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?​
  5. Do you know how to capitalize headings and titles?

    ​It is important to use correct capitalization when writing titles/headings for things.

    "The Lord of the rings – Return of the king"

    Figure: Bad Example – The first letter of the first and last words should always be capitalized

    "The Lord of the Rings – Return of the King"

    Figure: Good Example – Only conjunctions and prepositions (both having similar rules) should not be capitalized e.g. at, on, but, and, with etc.​​

    ​It's best to only do this on main titles (which are important), and leave subtitles in normal sentence form. Basically it saves hassles... English is a confusing language and there are too many variations that cause too many arguments.​

    Good Example - the main title has capitalization and the sub-titles don't

    Figure: Good Example - the main title has capitalization and the sub-titles don't​
  6. Do you add a useful figure (AKA 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 and Formatting​

  7. Do you highlight actions correctly in your document?

    ​When highlighting items (file names, user commands etc.) be sure to:
    1. Distinguish the items from the rest of the surrounding text; and
    2. 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
    ​UPPER CASE​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.

    Remember: Never Underline the text when it isn't a link as per the rule: Do you use underlines only on links?​
  8. Do you include version numbers in your file?

    ​It is very important to have your Word, PowerPoint, PDFs 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.
  9. Do you know how to make quotations easier to identify?

    ​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.​

    Bad Example - adding quotations

    Figure: Bad example - It is hard to tell where the quote is​

    Good example of added quotation

    ​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:

    How to add a quote in Windows Live Writer

    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.​


  10. Do you make numbers more readable?

    Remember to use dividers when quoting phone numbers or large sums.

    ​1. 2721654230
    2. Phone: 8583532311

    Bad Example: These number are unweldy and difficult to read

    ​​​

    ​​​​​1. 2,721,654,230​
    2. Phone: (858) 353-2311

    Good example: A comma, a dash and some spacing makes these large digits easier to read
  11. Do you refer 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.

    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.​
  12. Do you use active phrases? (No zombies please)

    To get the most out of your communications, your writing should be compelling and direct. The best way to ensure this is to use active voice. 

    ​For example:

    When the CD is inserted, a Windows dialog will be shown.

    Figure: Bad Example - This example is using a passive voice, and does not address the reader or from the point of the subject (the software in this case).

    When you insert a CD, Windows shows a dialog.

    Figure: Good Example - This example uses the active voice to address the reader, and is more direct and engaging.

    An easy way to tell if you're using the passive voice is to add "by zombies" after verb. If your sentence still make sense, you're using passive voice. 

    The email was sent by zombies

    Figure: Bad example - This sentence could be more engaging

    ​​​​Zombies sent the email ​

    Figure: Good example - Now that's a more engaging sentence

    3 reasons you should avoid passive voice:

    1. ​Passive voice uses more words​ - in the figures above, the "Bad Example" uses 6 words whereas the "Good example" uses only 4
    2. It's less logical - instead of having the subject do something to the object, the object does something to the subject
    3. It's less clear - In the bad example above, you don't know who was acting until the end of the sentence, whereas in the good example, you know immediately. 

  13. Do you use a spelling and grammar checker to double check your content is professional?

    Improper spelling, grammar, and punctuation in your content gives a bad impression of your company. It is unprofessional so always use a 'Spelling & Grammar' checker prior to saying 'done'. 

    Web Content

    Go to Grammarly, create a New Document and Paste your content to check your text.

    grammarly.png
    Figure: A typo caught by Grammarly​​

    It's also a good idea to install Grammarly Addon for Chrome  so you can automatically check web content while editing in a CMS for example.

    Documents

    Copy and Paste your content into MS Word then press F7 (or on the ribbon go to Review > Spelling & Grammar) to check your text.

    Use Microsoft Word's spelling and grammar checker to confirm your content is correct
    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?

  14. 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.
    For example:

    ​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
  15. Reference: Do you use quotation mark for controls?

    ​​​​​Quotation marks 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.
  16. Reference: 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

    We have a program called SSW Link Auditor​ to check for this rule. We offer a rule sample pag​e​ for demo scan.​​


  17. Reference: 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.
  18. Tiny: 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.

  19. Tiny: 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:
    1.    Select File | Print. The Print dialog should now show.
    2.    Select the number of copies and click Print. The file should now print.

    Figure: Bad Example - Using "should" implies uncertainty

    To print your document:
    1.    Select File | Print. The Print dialog is shown.
    2.    Select the number of copies and click Print. The file will now print.​

    Good example - Using present or future tense implies confidence

    This is *not* detected by SSW Code Auditor ​because it picks up false positives.​
  20. Tiny: 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 Webfo​rms 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
    We have a program called SSW Code Auditor​ to check for this rule.
  21. Tiny: Do you use "Try Again" instead of "Retry"?

    ​​They are similar but "Retry" is a more like computer jargon, whereas "Try again" sounds friendlier and more human. 

    ​​​Use Try Again, not Retry

    Figure: Internet Explorer uses "Try Again" instead of "Retry"​
  22. Tiny: Do you use "Taskbar" instead of "Task Bar"?

    ​​This is a common item that trips people up: taskbar is one word, not two. 

    Taskbar is one word, not two

    Figure: Good Example - You should use the "taskbar" over "task bar"​
  23. Tiny: 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 example – two separated words

    You cannot change the world.

    Figure: Good example - using these terms in one word

    We have a program called SSW Code Auditor​ to check for this rule.​​
  24. Tiny: Do you know "email" does not have a 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."

    We have a program called SSW Code Auditor​ to check for this rule.
  25. Tiny: Do you know commas and full stops always should have 1 space after them?

    ​​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
  26. Tiny: Do you avoid using "that" when it's not needed?

    'That' is occasionally an unnecessary addition to a sentence, especially if it's a title that would benefit from being short and punchy. As such, avoid using "that" in a title wherever possible.

    "Building Software that People Understand"

    Figure: Bad Example - unnecessary "that"

    "Building Software People Understand"

    Figure: Good Example - without the "that", the setence is concise and has more punch
  27. Tiny: Do you avoid full stops at the end of bullet point lists?

    ​​Excess punctuation without a purpose can make a document or web page look overly busy. For a list of short sentences, don't have full stops at the end of each bullet point. The exception to this rule is when you have more than one sentence in a single bullet point.

    For example:

    • Sentence 1.
    • Sentence 2.
    • Sentence 3.
    Figure: Bad Example - Too much punctuation

    • Sentence 1.
    • Sentence 2. Sentence 3
    • Sentence 4
    Figure: Good Example - Full stop is only used in the bullet point that has multiple sentences, except in the last one​
  28. Do you know when to use versus and verses?

    ​​​​Words like “verses” and “versus” are homophones, meaning they are pronounced the same, but have different spellings and different meanings.

    When using a homophone in a sentence, it is important to ensure you are using the correct word, as if you are not, it won’t be picked up by your spell check and you'll look less intelligent.

    ​In this case, “verses” refers to lines of poetry or bible passages. “Versus” refers to 2 or more parties in opposition to one another, especially in sports or legal situations.

    “Versus” can be shortened to “vs.”, which is common in sporting situations, or “v.”, which is the standard abbreviation for legal scenarios.  

    Matthew 5:41 is one of my favourite bible versus.

    Figure: Bad example: the wrong “versus” is used

    Floyd verses Mayweather.

    Figure: Bad example: Floyd did not poetry Mayweather

    “Brown v. The Board of Education.”

    Figure: Good example: in a legal context, “versus” is abbreviated to “v.”

    Adam penned many verses about his lo​ve for .NET development

    Figure: Good example​


  29. Do you use "Note" instead of "NB"?

    ​In a piece of writing, both “NB” and “Note” can be used to add a piece of information or attract the reader’s attention to an important detail. Of these 2 options, it is better to use “Note” than to use “NB”. 

    ​This is because NB is old-fashioned – it is the abbreviation for “nota bene”, Latin for “note well” – and its meaning is not immediately clear, whereas the meaning of “note” is immediately obvious. It is always better to use plain English, and to avoid abbreviations that could be confused for something else. Therefore, you should use “note” in your documentation to ensure your meaning is clear. 

    NB: It is important to track how long this process runs for.​​​

    Bad example: NB is unclear and old-fashioned


    ​​Not​​e: It is important to track how long this process runs for.

    ​​ ​Good example: It is obvious what we mean when we use "Note"