How to Write Technical How-Tos
In understanding how to write technical instructions, it’s best to understand how people read them. Most readers will want to know: (1) what you’re doing, and whether it’s relevant to what they are trying to do; and (2) how you did it.
This suggests a simple strategy: first, write about what you’re doing and why, and then, explain how to do it. If you leave out the why, or make it hard to find, your reader will have to closely examine your explanation to understand whether your technique is relevant to them at all. If you leave out the how or make it hard to find, your reader will struggle to replicate your efforts.
Unlike ordinary prose, technical instructions require the reader to retain exact, complicated, and concrete information. This means that technical prose can be very dense.
Additionally, remember that people often skim, read out of order, or jump to the bit they care about. Therefore, technical instruction benefits from a fractal structure: as you give instructions, at each step you should be clear on the reason for this action (the why), as well as enumerating clearly how to do what you did (the how).
Spare your reader the effort of disentangling the order, purpose, or context of your instructions. When possible, use semantic structures like separate headers, bullet points, or numbered lists, instead of relying only on explanatory paragraphs. Choose structures which mimic the relationships between the different elements comprising your content. You are trying to give your reader a model structure to order their thoughts in.
Headings & subheadings
Technical information usually lives in a hierarchy of information, with more important or fundamental ideas coming before less important or fundamental ones. For the most part, you will want to put them in this order, with the most important ideas at the top (in particular, this means why you are doing what you are doing), branching into more and more specialized content as you read down.
Break your content up into intuitive sections. A good heuristic for an intuitive section is that each one should contain a why → how pair. If your section contains several sub why → hows, break it up further into subsections. For instance, the Structure heading (why: use structure, because it helps your reader retain complicated technical information. how: choose structures which convey the semantic relationships of your content) is followed by several sub-headings, each talking about the different relationships conveyed by different types of structures.
At every step of the way, make each individual element as stand-alone as possible. This will help even readers who skip around get the most out of your document. Moreover, focusing on this property is another good heuristic for determining whether your structure is intuitive.
Use descriptive titles. Headings give your reader an idea of what box the current information belongs in. This will help them find the right section if they’re skipping around, and it will also help them keep their thoughts in good order.
Add hierarchy visually. You can use hierarchical semantic structures (e.g. numbered headers 1.2, 1.2.1, or headers with different levels of visual priority) to convey an idea of an idea’s relative importance.
Numbered lists are the most intuitive structure for many forms of technical how-to. This is because we are typically issuing a series of instructions that should be executed in order, and do not make sense out of that order.
You can also use numbered lists to convey a series of principles, or any other set in which it is important for the reader to retain all of, rather than some of.
In general, if you are uncertain whether to use a numbered list or a series of bullet points, consider the following two questions:
- Is it important that these events happen in order? (If yes, use a numbered list.)
- Is it important that the reader retain all of these elements? (If yes, consider using a numbered list. If no, consider whether your list is actually a coherent and important set, or if you are perhaps mixing sets.)
Unordered lists longer than two elements (and some two-element lists) can be conveyed as bullet points. For instance:
- a list of options which your reader must choose from (For this step, you may choose…)
- a list of requirements (You will need…)
- a list of takeaways (You will learn…)
However, because they are less structured than numbered lists, readers are less likely to retain all of the elements of a list of bullet points. In general, bullet points are not as memorable as numbered lists, so they are more useful for illustrative points, rather than for vital ones.
The Why: how to describe rationales
Keep in mind what your reader wants to know. What is the most important thing your document explains? (Or, for a subheading, what is the most important thing this part explains?) This is the why your rationale should approach.
For instance, a piece about integrating Shibboleth into your app might be focused on:
- Why did you choose Shibboleth instead of OAuth or another authentication protocol? (In this case, your why should explain the requirements you are using to choose between authentication protocols, and briefly elucidate why Shibboleth was the best choice, and your how should talk about how you assessed each option.)
- How did you choose to implement your Shibboleth/app integration? (In this case, your why should explain why this approach is better than the other approaches, and your how should describe how to implement your approach.)
Make sure that you are answering the question your reader wants to know. And of course, different parts of the same piece might address each of these concerns in turn — in which case, make sure you are answering the right question in the right place.
In general, rationales benefit from being concise. You are trying to explain as quickly as possible what value your document will have to a reader.
The How: how to enumerate instructions
Unlike rationales, instructions benefit from being explicit. Specifically, you want to make sure that you have fully described the steps your reader will need to follow to replicate your results.
Order your instructions. Make sure that your instructions occur in the order your reader will need to implement them.
Explain your rationales. At each step, explain what this step is achieving. What piece of the overall goal does this satisfy?
Be specific. Give explicit code snippets, terminal commands, protocol names, etc. whenever you have them. If you have a repository that your code lives in, link to it. If you have found other resources useful, link to them.
Use explicit structures to call out explicit actions. Use a distinctive format to call out specific actions. Many publishing platforms have a specific format for code snippets: take advantage of this when possible. If you don’t have that option, you might consider formatting like fixed-width fonts to achieve the same effect.
Additional Steps: links, pictures, & reviews
Links. Don’t link to anything that you don’t think is useful. In general, you should link to (a) further explanation that you don’t intend to go into in this document (e.g. previous posts on the subject, or posts that disagree with yours) and (b) other people’s reference materials (e.g. an API or protocol spec).
If you are debating between multiple resources for a topic, link the most useful one, even if it is not as canonical. There is no reason to link bad documentation.
Pictures. Pictures have a few uses in documents:
- They break up the flow of text, giving your reader a moment to breathe.
- They illustrate important content that is difficult to describe in words, but easy to understand in pictures. (For instance, block diagrams of the internal workings of systems or protocols).
- They allow your reader to double-check whether the result they are getting is similar to yours. (For instance, a screenshot of a long output from a terminal command.)
In general, pictures should fulfill more uses than just #1.
Review. Get someone else to read your article before it is published. Ideally, this reader will be someone who (a) has approximately the technical skills you expect your readers to have, but (b) has not performed the task you are describing. They will be able to tell you where your structure is muddled, your thoughts are unclear, or your instructions are vague.
Timeliness. Technical details frequently change. Make sure your document is annotated with the date you last updated it, so that readers can (a) get a sense for whether the landscape is likely to have changed since then and (b) look for more recent sources, if something in your directions does not seem to line up anymore.
Comments. A medium that allows comments can help provide your reader with further helpful detail. For instance, commenters might post with details you forgot, report problems you didn’t experience, specify further options, or update details that have changed since you wrote the original document.
Ideally, you should keep an eye on your comments section, to provide answers (if you have them) and to prevent any internet weirdness from developing.
FAQs. Some types of document are greatly augmented by FAQ or Common Problems sections. For instance, if there are common edge cases in the protocol you have outlined, or if you need to explain some part of your decision-making in greater detail (e.g. Why didn’t you use xyz library?), some type of question/answer section may be helpful.
You should think of FAQ sections as a response to potential responses to your document, not a fundamental component of your instructions. In other words, if this information is only relevant to certain types of reaction to your document, it should go into an FAQ section.
Open Questions/Non-Goals. There are a couple of different ways to talk about questions that you are not answering: (1) as a future direction, pointing up unanswered questions so that readers will think about them (i.e. Open Questions); or (2) to be clear about the limitations of your document (i.e. Non-Goals.)
In general, both of these should be very short, focusing on only the most important Open Questions or Non-Goals. You will generally want to put an Open Questions section at the end of your document, as that is where your reader will be most qualified to think about them. Non-Goals sections, if you choose to include them, should go near the top, probably as part of your initial why, as that is when they will provide the most useful clarification for your reader.
People read technical documents so that they can take action on projects of their own, not for some kind of vague elucidation. Your goal as a writer should be to enable them to take those actions as quickly as possible after consulting your document.
If you are not sure where to start, try to break your topic down into a why → how structure. This is approximately the mindset your reader will be approaching your document with, so thinking within this framework will help you see what to prioritize for them.