Why we need documentation in the first place
There’s an old adage attributed to Steve Jobs (Or is it Sun Tzu? I can’t remember) that goes something like:
“If the product needs a manual, the design has failed.”
The idea is that your product should be intuitive, and if you need to explain how to use it, you’ve already lost.
Now I’m no product design expert, but I can tell you for sure that just about every software product in the world has ignored this advice. Products have never been as feature rich and complicated as they are today…and thus we require a bit of guidance to navigate them. Just think about how many settings are in Gmail, how many functions are in Excel, and how many keyboard shortcuts there are in Discord. Obviously, they need to be written down somewhere.
And nowhere is this more true than developer tools and infrastructure. Because most products built for developers are not visual – they make use of code editors and the Terminal. They’re APIs and SDKs, libraries and frameworks. How are you supposed to know which API endpoints you can make requests to? What data do you need to include with your request? And what data can you expect to be returned? What does it mean when you get a specific error code?
The answer is documentation, and just about every developer-focused product has it. Documentation walks through all of the functionality of your product, and how to use it. It covers which API endpoints are available, and how to talk to them. It gives you examples that match common tasks you might want to accomplish. It might even walk through the conceptual logic behind the product (more on this later). All in all, it gives you the manual you need to navigate a product that has little or no visual counterpart.
And it’s not only “non visual” products that need docs. If you think back to the 2000s, imagine yourself stuck in some clunky Microsoft program, desperately trying to discern between two different dropdowns that seem to do the same thing. At some point, products reach a level of complexity that requires a manual – visual or otherwise.
Historically, documentation was just “something that you had to do.” A necessary evil. But over time – as the developer tools and infrastructure market has gotten more crowded – docs have emerged as an opportunity to differentiate your product. Thanks to pioneers like Stripe, we’ve started to see that incredibly well written, beautiful, interactive docs are more than just a manual; they are great marketing. In fact many developers will go straight to your docs when evaluating your product, totally bypassing the stunning marketing site you paid some agency $100K to design.
The anatomy of good documentation
The fact that documentation exists does not mean it is good. In fact one could argue that the majority of documentation out there is in fact bad. So what do good docs actually look like?
The most important things that distinguish good docs are:
- Accuracy: are your docs correct? Do all of the things you explain accurately describe what the product does? Are they up to date on the latest functionality and changes?
- Coverage: do you cover all of the functionality of your product? Do you have sufficient tutorials for the common tasks users might want to do? Are you missing anything?
These might seem simple, but are far from it. Making sure all of your docs are up to date and cover your whole product surface area – as your engineering team works tirelessly to update and expand that product – is in some senses a sisyphean task. Your product is always changing, and your docs need to too (more on this later).
What about organization? How are good docs structured?
Diátaxis is a conceptual framework for putting together good documentation. They break up good documentation into 4 quadrants or groups:
- Tutorials – teaches someone how to do something in your product, with the goal of learning something new.
- How-to-guides – teaches someone how to accomplish a particular goal of theirs (e.g. integrating with one of the systems).
- Explanation – simply, explaining how things work.
- Reference – just listing out technical descriptions of the machinery and how to operate it.
Good documentation covers all of these areas, and covers them well.
Ultimately whether your docs are “good” or not just depend on your goals. Some teams are focused on docs making onboarding easier, while others mostly want to reduce support ticket volume. Some data from GitBook’s State of Docs 2025 survey:
Essentially, how you build your docs – and what makes them good or bad, to some extent – is all about what you want to accomplish with them.
The last thing I’ll mention about good docs is that they should have a soul. Your documentation needs to reflect who you are as a company and what makes you special, not just some template you found on the web. There are a million ways to do this; not every docs site needs to look like Stripe. The docs for Django – a popular web framework for Python – are a lot more barebones, but still feel right.
Good documentation is easier said than written done
If building good documentation was easy, everyone would do it – it is not, and they do not. It is, in fact, very hard:
- It takes time and effort that could be spent on building your actual product. Especially at the earliest stages of your company, this tradeoff is hard to grapple with.
- Your product is constantly changing and your docs need to change with it. Are you going to be disciplined enough to make sure every product change gets a docs change too?
- Writing isn’t everyone’s strong suit, especially software engineers.
- There are thousands of conceivable use cases for developer tools; which ones should you cover in the docs?
Then there’s the question of logistics. Docs are essentially an entire application. Where do you host them? How do you make it easy to create and edit new docs? How do you make sure it’s reliable, so an influx of new users doesn’t make it crash?
This is why, in practice, many (most?) docs suck. They are outdated, they are visually decrepit, and they are poorly written. They are missing coverage of the one feature you need the most. They’re trying so hard to cater to everyone, they’re bloated and impossible to browse. They have typos. Or worst of all: they lack a soul.
Using a managed docs platform like GitBook
The good news is that you don’t need to reinvent the docs wheel. Unlike 5-10 years ago, today there is incredible software that makes it significantly easier to build and maintain high-quality documentation.
One of those pieces of software is GitBook, the generous sponsor of this post. Think of GitBook as the engine for all of your docs, API-related or otherwise – they take care of everything from building and publishing docs to customization and analytics. You can get a sense for what your GitBook-hosted docs would look like by checking out Snyk’s docs, the application security company I wrote about a while back.
GitBook focuses on the collaborative nature of docs – it’s not just for developers. So you can use their slick UI to author documentation, or use a Git-based workflow in code to make your developers happy. For PMs, support agents, or technical writers contributing to your docs, having a good visual editing experience makes a big difference.
After writing or editing your docs, all you need to do is click “merge” + publish and GitBook gets them on the web for you. The docs are hosted on their servers, so you don’t have to worry at all about infrastructure or reliability.
Another nice thing about platforms like GitBook is that you don’t need to worry about styling – and I promise you most developers do not want to worry about styling. You can customize everything from your logo and colors to fonts, icons, and even link styles.
Astute (or hype-train maxxer) readers will wonder – what about AI? GitBook has a native “Ask AI” feature that turns your docs into an interactive chatbot you can just talk to. They’re also working on an MCP server so the chatbot can bring in custom data sources and even take actions from docs.
The last thing worth mentioning is customization. All of your users are different, but they have to read the same docs… or do they? GitBook just released their new adaptive content features that let you do exactly that: customize your docs to your users. You can do things like gate docs to particular types of users (e.g. enterprise docs for enterprise users), have separate landing pages for new users vs prospective customers, or even turn sections of a page on and off based on feature flags.
If you’re thinking about how to level up your documentation – or even just start covering the basics – you can get started with GitBook for free.
