What is Technical Writing?
And does it differ from other types of writing?
When I was a student, I had friends and family ask about my major, and the conversation usually went like this:
What are you studying?
Technical communications.
What does that mean?
Um… I would write technical documentation.
And the conversation devolved from there.
When I got a job as a technical writer, the conversation turned into this:
What do you do now?
I’m a technical writer.
What does that mean?
I write end-user documentation for software. So user guides, troubleshooting articles, stuff like that.
Better, but not perfect. After all, what layman immediately understands “end-user documentation”?
Now, after a lot of thought (and a dozen bumbling conversations), I say this:
I explain complex things in a simple way to help people get the information they need.
Ta-da! My mini sales pitch. Let’s expand.
What is Technical Writing?
Technical writers explain things. We take complicated concepts and break them down into pieces. But describing the complex is only half the battle. There are many aspects, but let’s cover four main points.
1. Organizing Information
Technical writers organize information in a logical way. It isn’t enough to provide users with helpful information, we need to provide it at the right time and place. This is referred to as information architecture, and it is the holy grail of good documentation.
Information architecture is widely regarded as the intersection of users, content, and context.
As it relates to documentation, this can be as granular as the structure of a document, or as holistic as the taxonomy for a help center.
2. Writing for an Audience
A good technical writer creates content that is relevant, useful, and accurate. They also write content geared to a specific audience. For example, an IT professional has more technical knowledge than the average user. They don’t need you to explain what transport layer security (TLS) is, whereas a layman might.
3. Orienting Documentation by Function
There are many different types of technical documentation — troubleshooting articles, user guides, manuals, API documentation, and so on. Regardless, all technical documentation serves at least one of four main functions:
- Tutorial
- How-to guide
- Reference
- Explanation
The following table, courtesy of the Documentation System by Divio, describes these further.
As a note, I’ve found the best how-to guides also incorporate explanations, usually in the form of an introduction or overview. Providing steps to accomplish a goal is all well and good, but providing context for the goal is even better.
For example, let’s take my list from above. Each of these types of documentation maps to a specific function, or combination thereof:
- Troubleshooting = explanation + how-to
- User guides = explanation + how-to
- Manuals = reference
- API documentation = reference + how-to
4. Communicating Plainly
For all its differences, technical writing is still writing. The basic structure, spelling, and grammar are consistent with other types of writing. The key differences are in purpose and style.
Purpose: Convey information, appeal to reason.
Style: Unobtrusive.
Why unobtrusive? Well, you read a technical article because you’re already curious about the topic. There’s no need to arouse interest — you don’t need flashy headlines. Technical writing is a vehicle for presenting information. Good technical writing doesn’t attract attention to itself.
If an article is well written, you don’t even notice the writing style. You’re focused on the subject matter. If an article is difficult to read, you get distracted and focus on the nuances or issues in the writing.
A common way to phrase this is to “use plain, direct language”.
Summary
Technical writing is a style that focuses on the user's needs. It is simple, direct, and provides the right amount of information at the right time.
Good technical writing follows these principles:
- The content is well organized, both within the document and in the overall hierarchy.
- The content is written for a specific audience (read: appropriate technical level)
- The content serves one of the four main functions of documentation.
- The writing style is plain and direct.
Thanks for reading!
