Essential strategies for crafting grate developer documentation, with practical examples and insights from leading tech companies.

Everyone agrees documentation is important. But, seemingly, everyone also agrees most documentation isn’t good.

The gap between the consensus on what we should be doing and the consensus on what’s actually happening is wide. Everyone loves good documentation; everyone complains about bad documentation; and yet, almost every day, developers run into documentation that obstructs rather than clarifies.

A few companies (such as Stripe) and a few projects (such as Node.js) demonstrate how good documentation can be, but sometimes, examples alone make the work seem even harder. Before looking at examples, reworking your documentation can feel like an abstract problem everyone has a different take on; after, those examples can make you feel like there’s a gold standard that you don’t have the time or resources to reach.

Here, we’re going to break down some of the best documentation we’ve seen into a series of best practices. We’ll have examples for each practice, but the goal is to identify what makes good documentation great so that anyone can reach the same point.

1. Create transparent versioning #

Your documentation is as much an archaeological document as it is a guidebook. For open-source projects, especially, good documentation lays out everything a reader needs to know about the current product and everything they might need to know about previous versions.

Example: Node.js #

Node.js provides a detailed list of its features and shows which version added which feature.

Curious about os.platform()? os.release()? os.setPriority([pid, ]priority)? The first was added in v.0.5.0, the second in v0.3.3, and the third in v10.10.0 – all of which you can see at a glance.

If you scroll to the top, you can click through a list of every previous version and see the full documentation for each version at once.

Example: React #

React links from its documentation to GitHub, where it hosts a full release history. Each release comes with a bulleted list of additions and links to each commit.

Note that at the bottom, readers can also download the source code of each release.

2. Provide effective, comprehensive search #

If you’re building or reworking your documentation, an effective search feature is essential – no exceptions. But it needs to be good, too. If readers fail to find results for an input that should return results, they’re likely to be frustrated.

Example: Slack #

If you’re in Slack’s API documentation and searching for pages related to OAuth, for example, Slack’s search provides numerous helpful results. Before clicking through to any of the results, you can filter by document type and topic.

As you scroll, each result displays those types as well as brief summaries of the page.

Example: Algolia #

You’d hope Algolia – a company that provides search as a service – had a good search feature, and it does.

As soon as you hit the Algolia docs site, you can hit CMD-K (CTRL-K) to open the search bar.

When you start searching, you can select results with keyboard inputs, making things efficient.

And wouldn’t you know it, this search feature is powered by Algolia.

Counterexample: Twilio #

Twilio – a company typically known for serving developers well – provides a counterexample.

On the main documentation page, there’s no obvious way to search, and readers are left with almost thirty categories to click through.

If you click the sandwich menu, however, you’ll find a search bar – albeit, a clumsy one. The results page is barebone, and it’s unclear how the results are ordered. You might be better off Googling via site:https://www.twilio.com/docs.

3: Visual examples and diagrams #

Documentation doesn’t need to be beautiful, but it does need to provide at least some visual elements. The more complex a product gets – especially with integrations across other products or workflows between different processes – the more you need to provide graphic elements. A diversity of visuals is also helpful, such as diagrams and charts to illustrate workflows, and images and GIFs to illustrate interfaces.

Example: Stripe #

Stripe provides a lot of effective and often interactive diagrams throughout its documentation. In a page explaining how its checkout feature works, for example, Stripe has a sequence diagram.

Readers can see the flows between client, server, API, and checkout. Readers can zoom in and out to focus on different elements and hover over particular steps to see details.

Example: Slack #

In its second appearance in this article, Slack offers a couple of flowcharts to explain its notification flows (technically, these appear on Slack’s engineering blog).

The first, copied below, shows how a notification request flows through the web app and to a series of third-party services before hitting Slack’s mobile, desktop, and web clients.

The second flowchart, as the post explains, is more complicated.

The chart illustrates when and where to send a notification, but as Slack explains, the addition of more features over time, such as Huddles and Canvas, has made this series of processes even more complex. It’s hard to imagine explaining this without a chart.

Example: Auth0 #

If the previous example is on the granular end of the spectrum, explaining every step in a complex workflow, Auth0 provides an example on the other end of the spectrum. The example below is from the homepage of Auth0’s documentation.

This diagram functions as both a flowchart and a table of contents. It shows readers, at a high level, how the basic elements of Auth0’s product fit together. But each element is also clickable, meaning readers can click through to read deeper into an element that interests them.

As readers dig deeper, the flowchart table of contents stays at the top of the page, reminding readers where they are in the larger system.

Example: PenPot #

PenPot provides a few different diagrams and GIFs to explain its user interface and illustrate how readers can use its features. In the diagram below, PenPot shows its dashboard and provides a key for everything readers can click on.

As readers click through to explore how particular features work, PenPot provides detailed step-by-step GIFs.

Readers can use PenPot’s documentation to get an overview and then return as they start using each feature.

4. Clear and concise writing #

In the previous section, we talked about visuals, but most documentation is mainly text. And while it’s relatively easy to pick an ugly visual from a pretty one, it’s not always easy to write clearly, concisely, and well.

Some of the worst documentation looks good but is cluttered with confusing writing, bad grammar, and either too much detail or too little. Installing tools like Grammarly, reading books like The Elements of Style, and hiring a technical writer can help ensure your documentation is clean and clear.

Example: Amplitude #

Amplitude provides a bunch of great writing examples in its Analysis Overview. In its What Is Amplitude? section, in particular, the documentation walks readers through the key concepts necessary to understand the product’s features in more detail.

In the screenshot above, for example, readers get a broad overview and a table that describes each feature and provides a brief example. Amplitude even provides a TL;DR to ensure readers don’t waste any time if they don’t need more information.

Example: Docker #

As you pare your writing down to its most concise form, you can add layers of information architecture that guide readers from section to section and show readers when they should read what. Docker, for example, in a page guiding readers through the basics of containerization, begins with a list of prerequisites.

At the end of the page, which you can see above, Docker also provides a Summary and a link to Next Steps. The page itself isn’t very long, but still, it’s helpful to provide a summary so readers can consolidate what they just learned.

Example: Sendgrid #

A common failure mode for documentation writers is to under-explain. Frequently, the people writing the documentation have been immersed in the product and the niche for so long that it’s difficult to know what to explain and how deeply to explain it. On the one hand, barraging readers with jargon can make your documentation feel overwhelming; on the other hand, explaining every little thing can make your documentation feel verbose and tiresome.

Sendgrid provides a good example of how to thread the needle. Instead of explaining every term in detail every time a term appears in its documentation, Sendgrid links to a glossary that readers can peruse as necessary.

That said, as we mentioned in the Twilio example, a better and more prominent search feature would be welcome.

5. Interactive code samples #

One of Linus Torvalds’s best quotes, and there are many, is, “Talk is cheap. Show me the code.” A lot of documentation would be better if it followed this advice.

But whereas serviceable documentation merely shows the code, great documentation provides code blocks you can copy and paste, code samples you can download and fork, and code you can run from within the documentation itself.

Example: Supabase #

One of the cardinal sins of bad documentation is providing code through screenshots. You’re more likely to disappoint readers that way than if you didn’t provide code examples at all. Instead you should do it like Supabase where the code is presenetd as text with a copy button:

Supabase instead provides code examples through embedded code blocks that readers can easily parse and copy-paste.

Example: Rust #

Rust goes a step further by providing code blocks readers can copy and code blocks that readers can run in one click.

As readers go deeper and deeper, they can keep running code examples to check their understanding.

Example: React #

With React, readers can copy and paste code examples, but they can also edit, download, reset, and fork them.

The above example is a screenshot of what’s on the page normally. But as you edit the code example, the live results change

And if you want to do more, you can even fork some of the code samples.

React uses a tool called CodeSandbox, but there are a few other products with similar features, such as StackBlitz.

6. Organized structure #

Documentation – especially for complex products working across different programming languages – needs a well-organized structure to be approachable. Some readers need to be able to be guided from the first step to the last, and some readers need to find a particular section as quickly as possible. Good documentation serves all kinds.

Example: TailwindCSS #

TailwindCSS makes its documentation easy to read by repeating the same basic layout across many pages. In the following three screenshots, you’ll see the same elements: a title, a subtitle, and a table with code samples before a basic usage section that leads to more detailed information.

As readers click from page to page, it gets easier to find exactly what they’re looking for.

Example: Dropbox #

The Dropbox documentation is barebones, but it’s organized well enough to ensure readers start in the right place. On the homepage, the documentation provides a list of pre-built components and an API reference guide before leading into a list of SDKs.

Readers can click from the homepage to the SDKs most relevant to them and avoid getting lost in any sections irrelevant to them.

Example: Digital Ocean #

For many documentation sites, the homepage is a stale list of links. Digital Ocean makes things more interesting (without being distracting) by sharing the top ten most viewed docs pages.

Readers who are looking for something specific can still find what they’re looking for, but on the way, they might be intrigued by other Digital Ocean features or feel curious about a feature they never quite figured out how to use.

Once you scroll past this list, you can find a more traditional table of contents that includes an overview and numerous subsections.

7. Provide light and dark modes #

Research shows that about 92% of developers prefer dark mode (at least in their IDEs). Presumably, 8% of you are surprised, and the rest are shielding their eyes because almost all of the examples so far have been screenshots of light mode sites. Luckily, this torture isn’t necessary, and some companies are offering a light mode and dark mode toggle.

Example: Mermaid #

We considered, when building our documentation, the preferences of different readers and decided a toggle was worthwhile. As you can see in the screenshots below, toggling between each mode just involves hitting a slider in the upper right-hand corner.

Counterexample: WebComponents #

Most of the examples so far only offered light mode and could all be counterexamples. But WebComponents is an interesting one to pick out because it only has a dark mode.

If the study referenced above is accurate and applies to IDEs and documentation, then dark mode might be the one to pick. But if you have the option, both are better. Great documentation steals Our hope in distilling these best practices and sharing these examples is to one, provide you with a range of ideas you can borrow, and two, demonstrate how much you can learn by looking critically at all the documentation you come across.

In the style of the saying, “Good artists copy, great artists steal,” we recommend being pretty shameless about using any and every good idea that you come across. The more we share and the more we consolidate these best practices, the better documentation can become as a whole. And hopefully, we can start improving the state of documentation instead of just complaining about it.