The developer documentation stack
What do I actually need to publish developer docs people can use?
Six decisions between an empty repository and documentation that developers, search engines, and coding agents can all read: where the docs live, how the API reference gets generated, and how you find out what people actually read.
By Fabian HugUpdated
6 decisions · 16 tools
01 · Decision
Decide where the docs live
This is the decision everything else inherits, and the expensive one to reverse. The split that matters is not features but who edits: a static-site generator keeps docs in the same repository as the code and makes review a pull request, while a hosted platform gives non-engineers a browser editor and takes the build off your plate. Pick the first if your writers already live in git, the second if waiting on an engineer to merge a typo fix would kill the docs.
02 · Decision
Generate the API reference instead of writing it
Hand-written endpoint tables go stale the first time someone ships a field, and nobody notices until a developer files a bug against your own docs. If you have an OpenAPI description, one of these renders it and re-renders it on every change, which turns reference accuracy into a build step rather than a discipline.
03 · Decision
Make the prose consistent without a style meeting
Once more than one person writes, the docs drift: two spellings of your product name, three ways to introduce a code block, an inconsistent voice that reads as carelessness. A prose linter in CI settles that argument once, in a config file, and then stops re-litigating it in every review.
04 · Decision
Make the docs searchable on the page
Site search is how most people navigate documentation, and the built-in search that ships with a static generator is usually a client-side index that degrades badly past a few hundred pages. This is the step most teams skip and then blame the information architecture for.
05 · Decision
Serve the docs to assistants, not just to browsers
Developers increasingly ask a question rather than browse a nav tree, and they ask it of an assistant as often as of your site. Two different jobs hide in this step: answering questions on your own pages, and making your content fetchable by the coding agent already open in someone's editor. Both answer over your existing docs, so this is cheap if the previous four steps went well and actively harmful if they did not - an assistant grounded in stale docs is a faster way to be wrong. Publishing an llms.txt index and Markdown twins of your pages is the part you can do yourself, without buying anything.
06 · Decision
Find out what people actually read
Docs analytics answers one question worth the setup: which page do people land on before they give up. Both of these are privacy-respecting enough to run on a docs site without a consent banner in front of the content, which matters because a cookie wall on documentation is its own bounce rate.
How to read this
These are shortlists, not rankings. Every tool named here has its own directory entry with the facts it publishes and the date they were checked, and the order within a step is the order it was written in, not a verdict about which is better. We do not run these tools in production and we take no money for inclusion. Where a step has two options that genuinely suit different situations, it says which is which instead of picking one.
Hiring for this work
3 open roles match the documentation roles filter on the board right now.
Upcoming events on these topics