What I Know About Technical Writing

Note: This post was originally written in 2016, and things have changed a bit since then - both in the industry and in my own career. But I still think there's some valuable information here, so I'm leaving it up with this caveat and minimal edits.

The process of writing code, building apps, or developing websites is always evolving, with improvements in coding tools and practices constantly arriving. But documentation about code is one aspect hasn't really been brought along for the journey.

Technical writing is one of the darkest of dark arts in the domain of code development: you won't find too many people talking about it, you won't find too many great examples of it, and even hugely successful tech companies have no idea how to handle it.

So, in an effort to change that, I'm going to share with you what I've learnt about technical writing from building Facebook's Platform docs, providing documentation assistance to their Open Source projects, and creating a large, multi-part tutorial for Facebook's F8 conference in 2016. When I talk about the struggles of writing docs, I've seen it happen at the biggest and best of tech companies, and I've experienced how difficult it can be to get it right.

These tips aren't perfect, they aren't applicable to everything, but I've been writing technical documentation for a long time and I think it's important to share thoughts on this and have open conversations about how we write.

This is written from the perspective of technical writing, it can just as easily apply to shorter tutorials, blog posts, presentations, or talks.

Know Your Audience

While this list isn't really in any order of importance, this is almost certainly the biggest writing-related issue I've found in most pieces of technical documentation - documentation that seems to be for too many different people at once. You can generally divide up your technical audiences into three groups: absolute beginners, learning intermediates, and experts. The experts are the easiest group to write for, as their familiarity with the code or product means they're harder to confuse (and some of my advice won't apply to them), but the other two groups are often overlooked, particularly beginners.

So, before you start, decide which of these groups you want to target with your material, and keep your piece of writing focused on them. And because you can expect someone to increase their skill level simply by reading your writing, give them somewhere to go after they're done - connect your piece with the larger puzzle.

Conversely, for someone whose skill level is below that of your material, you want to ensure that they know this before getting into it, so explain clearly at the beginning any prior knowledge required, and link them to where they can discover it.

Forget What You Know About the Product

Don't really do that, but bear with me here. This is about making sure you write from the point-of-view of the intended reader, and don't write for yourself, or for your team, or for your company. That's easier said than done, but it's all about going back to understanding your audience, and forgetting what you've seen "behind the scenes".

The most basic part is erasing any kind of insider jargon you might have gotten used to using within your company or team. This happens so frequently, and yet it is an absolute death sentence to a piece of technical writing, especially when it is being read by beginners or intermediates. It's so easy to assume something makes sense when it does to you and all the people you work with. Try to seek feedback from outsiders as soon as possible to make sure you're not falling into this trap.

It can also be about describing things by their outcome, instead of their product names - for example Facebook used to have a product called "Connect" which would log you into apps or websites without needing a username or password. The docs used to organised around these product names, so you'd have a "Connect" section, a "Graph API" section, and so on. A substantial improvement was rebranding this to "Facebook Login", but that was still a product name. Better still, you'd call this branch of the documentation tree something like "Log people into your app or website using Facebook" — readers will find what the thing that they want to implement, and start reading, instead of getting lost¹.

Start Early in a Project

I'm willing to stick my neck out with a wild, educated assumption here, but I would guess that most tech projects think about documentation very close to launch, if they even manage to get ahead of it. I understand why - a lot of coding projects shift and evolve rapidly, especially as launch approaches, and it can seem wasteful to devote writing resources before things have gotten more solid or stable.

But I think this is a huge mistake, and I am going to assert that a technical writer should be part of any project from the very beginning.

To quickly go back a step, another reason why tech writing arrives late in product development cycles is because most people think it is just about a bunch of reference docs and maybe a couple of guides. But the content isn't as important, in some ways, as how it is organised. And planning the organisation of docs can begin in the first stages of any project, you can start laying out your topic structure very early on, and flesh out the content later.

Better still, when a writer starts thinking about this structure, it very often highlights flaws within the design of a product itself. While the team building something is usually pretty focused on that project alone, a technical writer has to think about how that fits within the existing structure of other existing products, as well as how the project is structured inside itself.

Keep It Short and With Clear Boundaries

Walls of text are a dubious way of reading about code — this is the most obvious thing I will say today. Code is best learnt by doing, with short pieces of accompanying text. This doesn't mean that long guides are inherently bad, in fact they're usually necessary, but that often they aren't properly structured which makes them seem more impenetrable than they really are.

If you've ended up with a long guide, start splitting it up somehow, whether that be over multiple pages, or preferably with lots of headings and a hot internal navigation system on a well-designed one page layout.

It's time I put my money where my mouth is and show you one of my own tutorials as an example. This tutorial part from my F8 2016 series is about as wordy as you could ever fear from a guide, but I believe that it is easy to read because each headed section is actually quite short. When you reach the end of a section, it feels like a natural resting point, which can prevent reader fatigue - use this to your advantage.

How do you split things up? It's probably too difficult to make a general statement on that, but sometimes it's obvious, such as describing a single function, or component, or API, or something similar. Let's say you're writing a step-by-step tutorial, I think that what works best is to end a section at a point where you've added something demonstrable to your code - somewhere you can hit run or refresh and watch the thing you just added in action. When a tutorial does this right, the thrill of achievement a reader feels at the end of each addition will give them the momentum to read the rest.

Show Me the Code

An obvious tip, but code examples are hugely important in docs. More than that though, the right kind of code examples are important.

Firstly, cut your examples down to only what you need to show, and what needs to be there for the code to be functional if copy and pasted by your reader. If you're writing a long tutorial, start with a skeleton piece of code, and gradually add to it within each section, keeping it functional at each endpoint, and never, ever skipping any steps. Some tutorials will take the approach of showing you the finished product first, and then breaking it down - personally I hate this method and don't think it works anywhere near as well as showing the reader how each new concept you introduce evolves the code that they're working with.

A nice trick for complex sites filled with lots of documentation is to reuse a common set of models, objects, or views throughout. This gives people a better chance of keeping track of what they're seeing in code examples if they're jumping between different topics.

Keep It Simple

Nearly everything said above is doubly true when talking about web technologies - here your beginners could be people with design as a primary skill and coding as a backup to that, and they will be more likely to be completely turned off by deeply technical terms. Simplicity is a virtue.

So, if you've described something as 'immutable', remember that "unable to be changed" is just as correct and much easier to understand. If you're showing some JavaScript, never assume that everyone is going to be familiar with the latest and greatest syntax. Equally, you might like to use shorthand syntax to keep your code tidy, but sometimes the longer syntax is more readable.

Remember that when you're writing for non-experts, it's easier for more people to understand it when you're using the simplest technical language possible, and you won't put off the experts by doing so.

There's a caveat here for Reference docs (i.e. docs which simply list off parameters, methods, or functions for APIs) which generally work better when they organise around product, because the people using them tend to be experts who just want to look up a parameter name quickly. ↩