We work hard to keep our API documentation up to date, but it seems like it's always incorrect pretty quickly. Developers change endpoints without updating the documentation, introduce new required fields without mentioning them, and deprecate features without marking it in the docs. Even when I make documentation part of the PR review process, reviewers still approve them as is. I've tried using automated tests to validate OpenAPI specs against the live endpoints, but those tests often break when response formats are changed. We even hired a technical writer for our API docs, but she left after six months because keeping everything current was just too much. It's frustrating when external partners reach out to us saying there's a discrepancy between what the docs state and what the endpoints return, or when new developers come on board and spend days confused by outdated documentation. Some companies, like Stripe, seem to have this down to a science. What do they do differently? Is it just a matter of more resources, or do they have a working system for keeping their API documentation in sync?
5 Answers
We started using a developer portal that automatically syncs with our OpenAPI specs. It helps keep the basic information current without needing too much manual work, which has been a game changer.
It's likely that Stripe has a dedicated team just for maintaining their documentation, which isn't something most companies can afford. They probably have multiple people whose job is solely to keep those docs accurate and updated.
Honestly, this sounds like a mix of poor PR review culture and lack of enforcement on the team's part. While some technical fixes can help, many of these problems stem from team practices. People need to prioritize keeping documentation accurate.
One solution to the issue of documentation being outdated is to generate your docs directly from annotations or comments in the source code. If developers update the code and forget to update their annotations, it could definitely harm the integrity. Some languages allow for generating the documentation from types, making it harder to break things without realizing it.
Exactly! In languages like TypeScript or Haskell, when swagger is generated from types, it’s really difficult to drift away from what the code is actually doing.
Keeping documentation up to date is essentially a separate job in itself. It might help to automate the documentation process or at least have some kind of standard practices in place to encourage keeping it fresh. Automated tools can assist in this way, ensuring what’s written in the code is reflected accurately in the docs.
That’s a great point! Knowing that makes me rethink what jobs I should be looking into. Thanks for sharing!