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

Last updated by Tiago Araújo [SSW] over 1 year 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.

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, 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

We open source. Powered by GitHub