#19 How To Write Better Developer Docs

People who’ve worked with me before know that I’m a documentation enthusiast. I believe that solid developer documentation for a product can be a major selling point for anyone using or purchasing a solution.

In my 5 years of writing docs, what stood out to me as a challenge wasn’t knowing what to write, but where to write it.

My team and I adopted Diátaxis last year as our north star for documentation, and now our docs are clearer than ever, both for readers and contributors.

Before jumping into solutions, I’ll first explain why documentation is important, what developer docs are, and how to write better docs.

Note: Whenever I use the word “docs”, I am am referring to Developer Docs.

---

Why is Documentation important?

Engineers read docs most (if not all) of the time. Whether that’s using a new framework, APIs, library, etc. Some engineers (including myself) tend to skip docs if they look too dry or confusing. Dry is fine if it’s a deeply technical document. Confusion is what throws people off.

To put it simply; the less the confusion, the better the docs are. A good example is Stripe Docs.

This guy gets it: https://news.ycombinator.com/item?id=31342008

Also, another way I think about good docs is: how quickly can you find things?

> I want a tutorial — where can I find it?
> I want to learn more — where can I find it?
> I want a code example — where can I find it?
> I want to look up an API — where can I find it?
> I want to test a solution — where can I find it?

If my docs don’t intuitively answer these questions, that’s a missed opportunity. Spending the whole day searching through docs is an expensive use of an engineer’s time.

A common mistake I’ve made (and seen others make) in docs is when authors try to answer two questions at the same time:

1. Telling you what to do.

2. Explaining everything as you’re doing it.

This generates an unnecessarily long document. If I’m an engineer who wants to deploy a database solution (say Amazon’s RDS), don’t explain to me how the underlying solution works. That belongs on another page. Just tell me how to deploy it.

The problem isn’t with the content; it’s how the content is being presented.

So, what’s the solution?

1. Think about the best docs you’ve read and take inspiration from them.

2. Reading Diátaxis.

First one is easy. My personal favourites are:

• FastAPI: https://fastapi.tiangolo.com

• Pandas: https://pandas.pydata.org

• Kubernetes: https://kubernetes.io

Let’s unpack the second one, Diátaxis.

What is Diátaxis

Diátaxis is a model for writing technical documentation (https://diataxis.fr).

It highlights that docs is composed of three things:

• Content: What to write

• Style: How to write

• Architecture: How to organise

We often know how to do content and style, but lack the skill for architecture.

The model breaks down documentation into four key sections: Tutorials, How-To Guides, Explanations, and References.

If you look at the diagram, Tutorials and How-To Guides belong in the Action region, they are meant to be followed step by step by the reader (i.e., hand-holding). Explanations and References fall under Cognition, these are resources that the reader can read or skim through anytime.

From left to right, Tutorials and Explanations contribute to skill Acquisition, they are meant to teach the new reader about your product. How-To Guides and References contribute to skill Application, they are meant to support the skilled reader on how to use your product.

---

Using Diataxis

To put this into practice, let’s say I’m writing a new documentations for a developer tool. I’d first design the navigation bar as follows:

From the diagram, you’ll notice that the first three blocks are meant for beginners—users whom I want to onboard to my new solution. The next three blocks are for onboarded users—people who know how to use my solution but have specific goals they want to achieve or specific information they want to look up.

In other words:

• Tutorials + Concepts: Users are learning

• How-To Guides + API References: Users are working

Note that some blocks might not be relevant to your solution (e.g., Concepts), but the important thing here is to make a clear separation between Action vs. Cognition and Skill Acquisition vs. Application when thinking about your docs.

---

Wrap Up

In conclusion, the three key components to focus on when documenting are:

• Content: What am I writing?

• Style: How am I writing it?

• Architecture: How am I organising it?

How to write better docs:

1. What are the best docs you’ve read? What common elements can you take from them?

2. Refer to Diátaxis as a reference guide.

A simple navigation bar to think about might look like this:

• Getting Started: User’s entry point

• Concepts + Tutorials: User is learning

• How-Tos + References: User is working

• Release Notes / Changelog: User is catching up