How 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
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
- Open the Workout app.
- Find the workout that best matches what you’re doing. Learn more about each workout type.
- 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.
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
“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’.
Click on the Backup Exec (BE) icon. Choose Configuration and Settings, and then Create Disaster Recovery Disk.”
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