Three types of documents in technical writing (with examples)

ow many types of documents are there in technical writing? Most articles online don’t list them. They mention guides, manuals, and procedures without connection to an audience. Other articles address specific subjects (e.g., “software documentation”).

Another way to look at documents? By intended audience. The following categorizes document types by audience.

DOCUMENTS FOR NON-TECHNICAL AUDIENCES

Graphic of the word “Steps” on a sheet of paper

Most technical documents created by technical writers are not for technical audiences. Sounds strange, doesn’t it? But, in my experience, it’s true. I even wrote an article to support this thesis.

Think about this: when I’ve worked with developers, I’ve noticed nearly all of them write — some very well, others, passably so.

Many “devs” are used to “writing as they go,” or documenting their coding, which can sometimes be a more efficient workflow than blocking off time for writing.

Sometimes devs have no choice but to create their own documentation because a dedicated technical writer can be a luxury, especially for small to medium-sized businesses.

What about non-technical end users? They cannot write the documentation they rely on for help!

Example document for a non-technical audience

A good example of a document (excerpt) for a non-technical audience would be this Apple Watch user guide:

Start a workout

  1. Open the Workout app.
  2. Find the workout that best matches what you’re doing. Learn more about each workout type.
  3. To set a goal, tap the More button next to the workout that you want to do. To skip setting a goal, tap the workout.
Apple watch display

4. Wait for the three-second countdown. To skip the countdown, tap the screen.

Clues you’re reading a non-technical document

A few clues that this example is a non-technical document include:

the simple word choice and phrasing

the large graphics

Other examples of documents for non-technical audiences

  • End-user guides
  • Knowledge articles
  • FAQs
  • Policy and procedure documents

DOCUMENTS FOR TECHNICAL AUDIENCES

Computer display

“Technical” technical writers are often embedded with software development teams. They need to know the language (code) the developers are implementing.

Code in technical documents can be copied and pasted into an application under development. Alternatively, code can be used for integrating multiple applications or to configure a database. If the code is wrong, it might break the application. If you know the syntax of Java or Python code, you’ll be better prepared to spot coding errors.

Example of a document for a technical audience

An example of a technical document includes this course content on ‘Documenting APIs’ from Tom Johnson:

YAML is a superset of JSON

For the most part, YAML and JSON are different ways of structuring the same data. Dot notation accesses the values the same way. For example, the Swagger UI can read the openapi.json or openapi.yaml files equivalently. Pretty much any parser that reads JSON will also read YAML. However, some JSON parsers might not read YAML because there are a few features YAML has that JSON lacks (more on that below).”

Clues you’re reading a technical document

A few clues that you have a technical document in front of you include:

the highly specialized words

the lack of large graphics

Other examples of documents for technical audiences

  • Configuration guides
  • Integration guides
  • Administrator guides

DOCUMENT HYBRIDS

And, of course, we can write documents to satisfy both technical and non-technical audiences — these try to strike a balance and often have a blend of the features above.

My favorite example: a Disaster Recovery Plan (DRP). During a disaster, there may be technical systems or applications that need to be restarted by non-technical staff because of technical personnel being unavailable (because of the disaster).

Example of a hybrid document

I like this disaster guide excerpt from Veritas — note the specialized wording alongside the large graphics:

“The problem: Steps to create a Simplified Disaster Recovery (SDR) ISO and perform a server recovery using the SDR CD or ISO.

Gather log files for technical support if recovery using SDR fails.

After the first Simplified System Protection (SSP) or SDR enabled backup, an alert is displayed: ‘Simplified Disaster Recovery Disk is not created’.

Three types of documents in technical writing (with examples) 1

Click on the Backup Exec (BE) icon. Choose Configuration and Settings, and then Create Disaster Recovery Disk.”

Three types of documents in technical writing (with examples) 2

So here you have it, the three technical document types by intended audience — a helpful way of categorizing the outputs from your technical writing mission, should you choose to accept.

References

Documenting APIs (Tom Johnson)
https://idratherbewriting.com/learnapidoc/

Apple Watch User Guide
https://support.apple.com/en-us/HT204523

Veritas Disaster Guide
www.veritas.com/support/en_US/article.100033528