Technical Writing Content Types

Technical Writing 101 - This article is part of a series.

Part 1: What Is Technical Writing?

Part 2: This Article

Last time, we talked about technical writing as a profession. Today, we’ll talk about technical documentation: what it is, how to approach it, and why it’s not as simple as “just ask ChatGPT to do it”¹.

Quick note: This post talks about technical writing in software and game development. It’s probably not as relevant to other industries.

Documenting with purpose #

Ask 10 people, and you’ll probably get 10 different answers. Some think it’s enough to walk the user through the UI–this menu does this thing, that button does that thing–then let them figure out the rest. Others like to record how-to videos instead of writing documentation. And then, there’s the odd devteam who insists their users are smart and they’ll figure sh!t out. (Spoiler alert: they won’t.) Heck, even technical writers can’t seem to agree on what we actually do.

Let’s try to puzzle that out.

We can start by thinking about the purpose of technical documentation. A computer program exists (say, Unreal Engine or 3ds Max). A user opens it for the first time and has no heckin’ idea what to do with it.

In the olden days, they would’ve opened the manual that came with it, which was either printed or bundled with the software itself, usually as a PDF. We’re talking hefty documents that could be tens or even hundreds of pages long². They were a one-stop shop for learning how to install, use, and troubleshoot the thing.

Nowadays, documentation is largely online and, if a software is popular enough, offical docs are also supported by user-generated content, like YouTube videos or answers on Stack Overflow. The democratization of the Internet also changed how users learn about a product. Back in the 90s, they might have read the manual end to end³. These days, they usually Google specific questions and click the first thing that seems to answer that question.

In other words, 20 years ago, users learned from a single source. Today, they could learn from a dozen. The user’s goal back then was, I want to know everything about the thing. In 2023, it’s, I want to know a specific thing about the thing. The purpose of technical documentation is to either answer that question, or give the user enough information to find the answer on their own.

Writing to meet user needs #

When documenting a new feature, I always start with two fundamental questions:

• Who’s going to use this?
• What are they going to do with it?

The first question gives me the target audience for what I’m writing, and that lets me make some educated assumptions that I’ll get into below. The second question guides me towards the type of content I’ll prioritize, and we’ll have a look at the three main (written) content types presently.

Know your audience #

Knowing the kind of users who are going to use a product or feature tells you several things:

• The minimum level of knowledge you can assume. If you’re documenting a specialized computer program (circling back to 3ds Max as an example), you can reasonably assume that they know what a window is, how menus work, and what clicking Cancel and OK does.

• Conversely, the average skill level of the users you’re writing for. This, in turns, informs whether you explain every speciality term, say, or if you stick to talking about the high-complexity stuff. For 3D modeling software, say, beginner users might need to be taught basic terms like mesh, normals, vertices, etc. before they can dive into more complex stuff. 3D artists who’ve been around for a while already know that stuff.
  
  A mismatch between the user’s skill level and your tone might make them feel either like you’re talking down to them (explaining simple things to pros) or that they’re out of their depth (other way around).

• The resources they already have, whether it’s current in-house documentation (e.g. for a previous version) or third-party content. This can help you quickly identify content gaps (what’s missing), doc rot (what’s out of date) and especially user pain points (the kind of things that make users go, Eff this, I’m moving to Blender.)

Know your content types #

There are many different ways to approach technical documentation based on audience needs, company brand and voice, writer workpower available, etc., but one of the quickest ones to grasp–and an industry standard for decades now–is the Concept, Task, Reference model.

Each one of these content types answeres a basic question about the software you’re documenting:

• Concept: What is the thing?
• Task: How do I use the thing?
• Reference: What are the parts of the thing?

To illustrate the difference between the three, let’s have a look at some examples from the Unreal Engine documentation.

• Concept: Global Illumination. A hefty overview of the subject that explains a number of concepts you need to understand before working with global illumination in Unreal Engine, written by a technical writer who’s also an expert in this particular area. It doesn’t dive into any how-to information but sticks to high-level knowledge.

• Concept: Niagara Key Concepts. This page goes through everything the user needs to know about Unreal Enigne’s Niagara VFX system, from its design philosophy to the main system components that the user will be working with.

• Task: Importing Assets Directly. This step-by-step walkthorugh shows how to import different types of content into Unreal Engine. In TV Tropes parlance, it’s exactly what it says on the tin.

• Task: Updating Projects to Newer Versions of Unreal Engine (yes, that title is a mouthful, innit 😅). A simple write-up of upgrading a project, this page doesn’t dive into the nitty-gritty (by cataloguing, for example, the different types of errors a user might encounter).

• Reference: Unreal Editor Interface. This complex page describes the main elements of the Unreal Editor interface and establishes some naming conventions. For example, the toolbar under the main menu is the Main Toolbar, so the expectation is that that’s what it’ll be called throughout the rest of the documentation. Similarly, the asset browser in the bottom part of the screen is called the Content Browser, the toolbar underneath is the Bottom Toolbar, and so on.

• Reference: Templates Reference. A page that walks through all available templates in Unreal Engine (5.1, in this case), gives a brief overview of each, and links to pages where the user can learn more about these.

And then, there’s API docs #

Everything we’ve talked about so far is stuff that can be grouped under a generic term like feature documentation. Feature documentation is authored independent of the code itself. API documentation, on the other hand, deals with the code itself.

API stands for Application Programming Interface. API docs are geared towards software developers, programmers, and other highly technical users. They can be generated from code comments using a tool like Doxygen, and they usually detail classes, functions, return types, and so on.

You can learn more about API documentation from this excellent write-up at Document360, which does a much better job than I could at explaining things (the last time I touched APIs was about three years ago, and all I did was an editorial pass). That said, unless your background has to do with programming, it’s unlikely you’d jump into technical writing and immediately be expected to write API docs.

Bringing it all together #

In theory, the concept-task-reference model sounds easy enough. In practice, I’ve rarely seen a whole docset that cleanly sticks to these three⁴. Even the Unreal Engine examples I linked above have some mixed content, and we’re far less prescriptive with these things in general.

Nevertheless, the logical flow of information for each content unit–whether it’s a set of pages documenting a feature, a one-page all-in-one guide, or even a smaller section of a much larger page–should typically go from copteutl information, to task-oriented content and, finally, reference tables, lists, etc.

In the next post, we’ll look at style guides: what they are, where to find them, and how to stay sane as a fiction author while producing content that’s the antithesis of creative writing.

Technical Writing 101 - This article is part of a series.

Part 1: What Is Technical Writing?

Part 2: This Article