9 components of great developer and API documentation

Documentation is the most underrated tool out there for company growth.

If you’re a dev-tools company targeting developers, documentation is your best marketing. Developers want to know what they’re working with and what your product can do; ideally, they can take it for a spin, too.

For everyone else, documentation is still essential; it’s the way people learn how to use your product. Rather than field customer support inquires all day, keep your customers and your support staff happier: Write documentation.

That said, we understand your hesitation. You’ve spent months building out this codebase, and the idea of documenting it all seems like a monstrous task. Worse, documentation requires a different mindset and a different skill set than coding. You’re not alone if you feel outside of your comfort zone.

To make it easier, we gathered 28 developer and API documentation examples and distilled them down into nine components you can use for your own documentation.

1. A clear home page (DigitalOcean)

Provide a map of your documentation so readers can more easily find what they need.

Your readers don’t necessarily know where they’re going. If they do, they don’t necessarily know how to get there. Rather than slap them in the face with code, give them clear directions.

DigitalOcean provides a home page that instantly orients users, giving them directions on where to go.

DigitalOcean's home page breaks their content into a simple-to-follow flow. As soon as you land on the documentation page, this flow shows you where to go.

The first step of the flow shows readers how to sign up for an account and start building. The next step shows readers resources that help them decide which product is right for them among the seven listed. The final step contains a billing section that provides users with a quick reference on billing questions, a common topic for DigitalOcean users.

Below these three sections, DigitalOcean provides a ticker for the latest updates.

Here, readers can get an up-to-date feed on the latest DigitalOcean releases. This section ensures that the home page is as much a home for experienced DigitalOcean developers as it is for newbies.

Blocknative, as you can see below, provides a top-down look at a bunch of resources readers will be interested in. This overview provides a map for the rest of their documentation, giving readers launching-off points for their interests.

A clear home page is especially useful if your company offers numerous products. UiPath directs readers to explore by product. UiPath (now valued at $35 billion) offers 20 different products (only three of which we captured here).

A section like this ensures that readers actually find the documentation that’s relevant to what they’re using. Even if your startup doesn’t (yet) have 20 products, it’s still useful to take a strong hand in directing readers.

2. A Getting Started guide (GitHub)

Whether you’re an expert or a novice, you need to get started somewhere. Effective developer documentation gives readers a Getting Started guide that directs readers down the path to understanding.

Let’s look at GitHub’s documentation. GitHub provides a Getting Started guide for their REST API that makes it easy for devs to dive into the topics that interest them.

A clickable table of contents on the left helps readers find the topics they need help with first. A concise overview section and an In this article list helps readers understand, at a glance, what the docs contain.

As you scroll, GitHub adds code examples to walk you from getting started to getting going.

Note, too, the humor: Little phrases like “logically awesome” and “tastes like JSON” keep the documentation from feeling boring. API documentation doesn’t have to be dry!

Snowplow Analytics is a good example of a simple, straightforward getting-started guide. You don’t need anything fancy; just a bulleted, linked list will do.

Trello goes a step beyond the prior two examples. Trello makes the promise that not only will you get started—you’ll get started in mere minutes!

Little else is as exciting to other devs as efficiency and creativity. Assure your readers that it doesn’t take long to learn before they can start building.

3. Simple explainers (Amplitude)

Creating good developer documentation requires empathy. Even when your readers are technical, they may not have the same skill set or knowledge base that you have. You’re steeped in your own codebase, in the use cases for your own product—readers will never know as much as you do. Take the time to break your product down for them. Doing so will make your work more accessible and will give your company more (and better) users.

Amplitude explains, in simple English, what their product does and what their documentation will explain.

In the first page of their docs, Amplitude takes the time to explain how Amplitude works. They use a simple example: a music player and the actions users take while using it—all of which Amplitude, the product, can track.

Amplitude explains how the product works in multiple ways. As you can see in the screenshot below, they start with text, move to code, and end on a graph. By engaging with multiple learning styles, Amplitude can have confidence that readers will walk away understanding the concepts they presented.

The less technical your audience is, the more important explainers are. Your primary audience for your documentation might be other developers, but the audience for the product might be someone else (product managers, in Amplitude’s case). That means your documentation needs to be reasonably accessible to both audiences.

Explaining things in simple terms (ELI5, for example) is easier said than done. It’s harder when you’re a product expert. If you have them, reach out to content marketers or technical writers to help.

At the bottom of MongoDB’s documentation home page, they provide links to free courses and to their community. Building out a “university” is a great way to help users educate themselves. For any information you haven’t thought to write yet, there’s always a forum, where expert users can help readers figure out their particular issues and use cases.

Courier takes a novel approach to educating readers. Courier devs stream regularly on Twitch and host recordings of those streams on YouTube—both of which their docs home page links to.

Courier proves that “documentation” can go beyond text. Courier is documenting their product live, helping readers/viewers understand and use it better. The live format also provides a way to increase user engagement. And by storing the recordings on YouTube, the Courier team still gets a durable asset they can reference as needed.

4. Compelling use cases (Twilio)

Devs will land on your developer documentation knowing little beyond “I can do something cool with this.” They may have heard about your product at a conference, on social media, or through word of mouth. For devs, documentation is the landing page, the home page, and the marketing funnel all in one. Again, rather than slap them in the face with code, provide easy-to-understand ways to use the product.

Let’s look at Twilio. Twilio starts readers off with a variety of use cases, instantly giving them ideas for how to use Twilio.

The more technical your audience is, the more important a section like this is, because it helps devs get started with your documentation and your product. The faster a reader is building, the better they’ll understand the product (and the more likely they’ll start to fall in love with it). Hands-on learning, even when talking about documentation, beats passive learning every time.

Spotify gives users the ability to browse by feature. Spotify saves their readers’ energy: Instead of having to waste a thought on what they could use the Spotify API for, Spotify gives them a kick start. They tell readers to start at a few popular use cases, trusting that once they start, they won’t stop.

The only thing better than use cases are actual stories. Slack highlights customer stories, showing devs exactly what other devs have done with their product.

Again, this is a time when you might want to use your content marketers or technical writers (if available). A good customer story can convince even the most stubborn of readers. Putting these stories in front of devs makes your documentation a marketing engine as well as an information center.

5. Language-specific documentation (Dropbox)

Relevance is your North Star when writing and organizing your developer documentation. There’s a lot of information you can dump on your users; taking the effort to make each drop relevant saves your users time and energy.

Let’s take a look at Dropbox. Dropbox routes users to different docs, depending on which programming language they use, ensuring that readers can find relevant information quickly.

Dropbox maps out SDKs for Swift, Objective-C, Python, .NET, Java, Javascript, and HTTP. Dropbox also provides raw HTTP documentation if they don’t support a reader’s SDK. And if that’s not enough, they also link to community-supported SDKs (though they make sure to note they don’t develop or maintain these SDKs, writing, “You may find these libraries useful, but note that these libraries are not affiliated with or endorsed by Dropbox.”).

In Webflow’s documentation, you can click between shell and Javascript and get section-relevant code for each.

‍

Auth0 documentation starts readers a step back, asking them to choose their application type before getting started.

If readers click on, say, Native/Mobile App, Auth0 then presents them with an even more relevant list of SDKs.

Remember: relevance. Ideally, you don’t want developers reading a line of code before they’ve selected which platforms will be relevant to them.

6. A simple layout (Stripe)

Your documentation can easily become a dumping ground for all the information you want readers to have. Counterintuitively, giving readers more information often leaves them with less understanding. Too much information can be overwhelming and can encourage readers to skim, skip, or leave.

Stripe is the model — as they are with seemingly everything — for developer and API documentation, both in general and in regard to design. Stripe provides a simple but compelling two-panel layout (look at their prebuilt checkout page doc, for example) that makes content easy to understand and track to relevant code.

Stripe puts plain English explanations on the left side, along with code that you can copy and paste on the right side. Clicking a concept on the left highlights relevant code on the right.

This layout lets devs pair their language learning with their programming, tying the concepts you’re explaining directly to the code they’re building.

Similar to Stripe, MagicBell displays information on one side and code on the other. As you scroll through the documentation, relevant code pops up in the right panel.

Confluence uses an even simpler, pared-down design for its product comparisons. Here, a table lists the server functionality on one side and additional details on the other.

This design, though less fetching than Stripe’s or MagicBell’s, nevertheless gets its points across in a way readers can understand and easily refer back to.

Another reason to use the two-panel design is that it allows you to put all your information on one page. Privacy uses a two-panel layout, which you can see below.

The difference with Privacy's page is that all of the content is within a singular page, which makes it more user-friendly. Users can find what they're looking for with a simple CMD-F and without ever leaving the page.

7. Interactive, compilable code (Rust)

If you want your readers to truly understand your product, give them the ability to really interact with the code, and even compile it. Code examples go only so far.

Let’s take a look at Rust. Rust provides code that you can not only copy and paste but also run and execute.

Rust walks you through your first moments, from creating a project directory to printing, “Hello, World!” Importantly, Rust also takes the time to review what actually happened when you executed each code sample.

If you can’t make code executable in your developer documentation, at least make it easy to copy and paste, as Avo does. Sure, you can select and highlight, but that’s not as easy as clicking a button. Make it easy.

There are tools out there to make your code easier to play with. For REST APIs, Postman is the way to go. Clearbit, in their documentation, gives you the option to run in Postman with one click.

The easier you make it for your readers to get their hands dirty with code, the better they’ll understand it, and the more they’ll learn to love your product.

8. Repetition (Docker)

DRY (don’t repeat yourself) is a common mantra in dev circles, but when your goal is education, you can safely repeat. Repetition (at least when you do it tastefully) locks lessons in your readers’ minds. Don’t be afraid to repeat something you want to make sure your reader understands.

Let’s take look at Docker. Docker repeats itself regularly in its docs. It includes recap sections that help shared knowledge really sink in.

These recaps sum up what they covered in the section, and they clue readers into what’s next. Plus, Docker uses “we” language to emphasize a sense of camaraderie, a sense that readers and writers are learning and building something together. You get the sense there’s a teacher or mentor right over your shoulder.

If you don’t like the idea of repeating yourself so much, create a glossary instead. Zendesk includes an A-to-Z guide of all the terms they use. When you reference one of these concepts, you can always refer to your glossary.

Segment has another way of using repetition. If you find your readers consistently asking the same question, you can add an FAQ to the bottom of your doc.

Even if you explained it in the documentation, an FAQ provides a one-stop shop for clearing up confusion.

9. Screenshots ... lots of screenshots (Retool)

One of your primary goals when writing developer and API documentation is to make the work you’re displaying feel approachable. If everything you describe is in text, the concepts are at risk of feeling abstract or obscure. Not everyone can easily translate from text to implementation.

Let’s look at Retool. Retool fills its documentation with screenshots and GIFs. Just take a look at the GIF below, particularly the proportion of images to text.

A combination of figures and text ensures that readers don’t get lost. And GIFs make user flows easy to understand and replicate.

Zapier uses a similar proportion of images to text. Every section, as you see in the screenshot below, starts with an image.

Appcues uses a similar proportion of images to text but also includes videos.

Videos, produced well, can be even more engaging. The more formats you can use in your documentation, the more inroads you give your developer understanding.

Developer and API documentation can be engines for growth

Treat documentation like the opportunity it is: Writing down a guide is a chance for you to practice your own knowledge while giving others access to it. As a dev, you’ve used documentation dozens, if not hundreds, of times. Use that empathy, and create docs like the greats.

If you do, you’ve simultaneously created assets that will drive user engagement, user retention, and user acquisition.