Indeterminate Pronouns - The Curse of Technical Documentation

One of things that we've been successful at hear at Edmunds is writing technical documentation that is clear and useful. It's taken a while. But now we're getting pretty good at it.

An important first step that we took toward improving the quality of our technical documentation was giving a lot of attention to eliminating the use of indeterminate pronouns.

What is an indeterminate pronoun? Consider the following sentence shown in Listing 1.

Listing 1: A sentence using an indeterminate pronoun

When building a REST service using a Cloud based application server, you'll do best 
to create a prototype of it first.

In the sentence shown above in Listing 1, and as diagrammed in Figure 1 below, please take note of the second to last word, it. Does "it" reference to the REST service or to the Cloud based application server? You really don't know for sure.

Figure 1: An indeterminate pronoun is one in which the noun being referenced is ambiguous

Now, if the sentence was written as such:

When building a REST service using a Cloud based application server, you'll do best 
to create a prototype of the REST service first.

...there is no ambiguity.

As I mentioned earlier, the use of indeterminate pronouns is the curse of technical documentation. If you're confronted with limited resources and personnel, the easiest way to clean up an organizations technical documentation is to address the use of indeterminate pronouns.

Here at Edmunds we use the wiki product, Confluence. One of the nice things about Confluence is that it allows us to create custom user macros that are used by writers and editors to make technical writing a little easier. We've created a bunch of user macros that allows editors to mark up a document when doing a technical edit. One of these technical editing macros that we've created is the {pro} macro. ({pro} is shorthand for indeterminate pronoun.)

Listing 2 below shows you how we use the {pro} macro to let writers know that there is an indeterminate pronoun in play.

Listing 2: The {pro} macro is a customer user macro written under Confluence.

When building a REST service using a Cloud based application server, you'll do best to create a prototype of ???Indeterminate pronoun[ it ]??? first.

The {pro} user macro is easy to use and highly effective. So, for all of you out there that work in a company that uses Confluence, we're posting the code for the {pro} macro so that you can add it to your technical editing toolkit. The code for the {pro} macro is displayed below in Listing 3:

Listing 3: The code for the {pro} Confluence user macro

<span style="font-weight:bold;color:red">???Indeterminate pronoun[</span> 
$body <span style="font-weight:bold;color:red">]???</span>