Principles for developer documentation

Writing documentation for software developers can be hard. Most of the time, your reader has a keen sense of what they want to get done and an impatience to get started.

Not only that but they’ve done this a hundred times before. Well, maybe not quite the same thing but they’ve developed against similar APIs, infrastructure software, and tools before. They know that bad documentation stands between them and getting their job done.

The good news is that you can follow some simple principles to put your documentation on the right track.

1. Empathise with your reader

Documentation is a conversation between two people. On the one side, there’s you. You know your product and, even where you don’t, you have access to people who do.

On the other side of the conversation is a software developer who wants to get something done. They don’t know your product but they want to.

Your documentation is there to provide a path for that developer to go from knowing nothing of your product to using it like a pro, even if there are lots of calling points on the way and not everyone will get to the end.

In practice, that journey has two primary implications:

1. You should understand who your target reader is.
2. You should write like a person who is helping another person.

The first of these means understanding your reader’s level of experience, what they want to get done, the context in which they work, and what they already know. Don’t assume who they are and what they know. Find out and write accordingly.

The second might seem a little odd. Think back, though, to some bad documentation that you’ve read. Perhaps it was overly formal and detached. Maybe it had a pseudo-academic style. Almost certainly, it was organised in a way that suited the writer more than you, the reader.

To write like a person helping another person, you should write in everyday English. Use examples. Put your writing into a context that makes sense to your reader. Use the active voice. Start at an appropriate point so that your reader has the background knowledge they need to make use of what you plan to teach them. 

You’re not writing a boring instruction manual. You’re taking the reader on the journey from no knowledge to usable expertise.

2. Make it skimmable

People come to your documentation to learn how to do something. Your job as that documentation’s writer is to help them become productive as quickly as possible.

Making your documentation skimmable helps your reader get the best return for the time they invest in learning your product.

At its most basic, that means frequent use of relevant headings. In a tutorial, for example, you can use headings to signpost key achievements, things that the reader needs to know, and shifts from one type of learning to another. 

Ideally, a heading should give the reader enough information so that they can quickly decide whether the paragraphs that follow will solve their need.

For example, “Java, Python, and Ruby support” is, in itself, useful information. Not only that, but it hints that the subsequent content will explain something about how those languages are supported. The less skimmable alternative, “Supported languages”, forces the reader to dive into the subsequent paragraph to learn what could have been shared in the heading itself.

Skimmablility goes beyond headings, though. Use icons, font weight, colour (but not exclusively, in order to maintain accessibility), pull-out quotes, screen shots, syntax highlighting, and more to turn your document into a map that helps people navigate the information they need.

3. Make it easy to navigate

Speaking of navigation, your documentation site should be easy to get around.

Visitors to your documentation will almost all want to do one of the following things:

• find out what your product does and how it works
• get started with your product
• learn how to do something specific
• look-up a particular item, such as the parameters required by an API call.

This isn’t just about structuring your site’s primary nav appropriately. From your front page to individual document pages, you must think about what your reader is likely to need as they make their way through your materials.

Link liberally, provide suggested next steps at the end of pages, make it clear where to learn any prerequisites.

4. Provide a map

If you know your readers, then you know their likely starting point.

Let’s say you’re documenting an API that will be used by people who are new to the concept of CRUD. In that case, you’d need to explain REST, CRUD, HTTP verbs as you go. For most developers, though, you could assume they already had experience working with REST APIs.

Either way, map out the journeys through your documentation. Provide guided paths by stringing documents together to take people from their starting point to their intended destination.

This applies to individual documents, too. In a tutorial, start where your reader is likely to find themselves and work forward in incremental steps from there. Tell the reader up-front what you plan to teach them and how. If there isn’t a one-size-fits-all guide, because some groups of readers will have differing needs, then write two or however many does the job.

5.  Put your reader to work

Writing code is an ongoing process of learning by doing. 

Practical hands-on experience is the only way that most developers can truly get under the skin of something new. That means your documentation should be all about showing, rather than telling.

Code samples are essential –– especially if they are syntax highlighted, provided in the languages your readers will expect, and easy to copy/paste –– but they’re not enough. Give your reader something to do as soon as possible. All throughout tutorials and guides, your reader should be able to follow along as you give practical instructions. It even applies to reference documentation, where examples help put things into context.

6.  Illuminate and illustrate

Text is great. It can often be the most efficient way to communicate something. 

At other times, though, a diagram or illustration will get a concept across much more effectively, and in less time, than several paragraphs of text.

Simple illustrations, showing how parts of a system interact for example, punctuate and support your text. Screenshots can be handy, too, but be careful to crop and annotate them appropriately.

Tell a story

Ultimately, to create effective and enjoyable documentation you need to put yourself in the shoes of your reader. Break down the stages that they’re likely to go through in order to learn your product and produce content that gives them the help they need when they need it.

Think of it as telling a story where your reader is the hero and their quest is to learn your product.

Photo by Suzy Hazlewood