Rules

Secret ingredients to quality software

Edit
Info

Do you refer to the reader and author consistently throughout your document?

Last updated by Joanna Feely on 06 May 2016 04:33 am (about 5 years ago) See History

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.

Adam CoganAdam Cogan

We open source. This page is on GitHub