Last Friday I got to sit down with Hahnbee Lee, CTO of Mintlify, to discuss documentation, - a critical and often overlooked aspect of software development.
Mintlify is one of the most popular documentation tool in the world, used by a large percentage of top startups, as well as companies like Pinceone and Anthropic.
Hahnbee co-founded Mintlify with Han Wang in 2022, and is an expert in docs, the role they play in developer experience, and what seperate great docs from mediocre ones.
Here are my key takeaways from our conversation:
1. Developers come to docs with a goal
I used to look at docs as a form of technical writing, like a knowledge base about a product or service. Hahnbee argues that at least for developer-facing companies, docs are the heart of their go-to-market.
When developers come to docs, they come with a goal.
Therefore, your goal as a doc writer is to get them to that goal as quickly as possible. The better you are at doing that, the more developers you can get using your product!
2. Separate Knowledge from Instruction
Hahnbee said a common failure mode for docs is when the instructional pages have too much information. She suggests keeping the instructional guides as lightweight as possible.
For example, on a page instructing the user on how to index a repo using Greptile's API, instead of:
"Next, to your header add your GitHub token and Greptile key. The GitHub token allows Greptile to access your repos, and the Greptile key links back to your billing account."
Say:
"Add GitHub token and Greptile key to header"
This is shorter and more readable, and additional context can be on its own page, like a glossary of terms or pages going over how stuff works. Every word on this page should serve the goal of getting your user to making a successful API call.
3. Attention to Detail
The risk of a buggy or sloppy developer tool, especially one that might go into production, is catastrophic. Documentation with mistakes are almost a warning of what comes next, and can subconsciously scare away your users.
High attention to detail has the opposite effect. It's a relatively low effort way to inspire confidence in your users. Think about the attention to detail in Stripe's docs, often considered the gold standard:
- Your Stripe key auto-populates in all the code examples
- When you set a code sample box to, say, TypeScript, every other box on the docs site also turns to TypeScript
What does this level of user obsession and attention to detail on the docs tell you about the people who built this product? They care, and they are meticulous. Characteristics that you would want your payment processor to have!
Watch the full episode here!
You can also listen on:
