Home
Do you refer to the reader and author consistently throughout your document?
  v3.0 Posted at 6/05/2016 2:33 PM by Joanna Feely

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

Related rules

    Do you feel this rule needs an update?

    If you want to be notified when this rule is updated, please enter your email address:

    Comments:

    Note: Social Media login for Yotpo is not working in IE or Safari, please use Chrome. We are waiting for Yotpo to fix it.