Regardless of what the author says about AI, they are bang on with this point:
You have the truth (your code), and then you have a human-written description of that truth (your docs). Every time you update the code, someone has to remember to update the description. They won’t. Not because they’re lazy, but because they’re shipping features, fixing bugs, responding to incidents. Documentation updates don’t page anyone at 3am.
A previous project I worked on we had a manually maintained Swagger document, which was the source of truth for the API, and kept in sync with the code. However no one kept it in sync, except for when I reminded them to do so.
Based on that and other past experiences, I think it’s easier for the code to be the source of truth, and use that to generate your API documentation.
Every time you update the code, someone has to remember to update the description. They won’t.
I get there are some exceptions where devs don’t have access to the docs, but I read this more like “Every time I update the code, I have to remember to update the description. I won’t.” Which, fair, but that’s the author’s problem. Writing docs is part of the job, table stakes stuff.
I mostly agree with your statement and I’m just nitpicking, but that document is not a source of truth if it has to be updated after the fact, it’s a reference.
Regardless of what the author says about AI, they are bang on with this point:
A previous project I worked on we had a manually maintained Swagger document, which was the source of truth for the API, and kept in sync with the code. However no one kept it in sync, except for when I reminded them to do so.
Based on that and other past experiences, I think it’s easier for the code to be the source of truth, and use that to generate your API documentation.
I get there are some exceptions where devs don’t have access to the docs, but I read this more like “Every time I update the code, I have to remember to update the description. I won’t.” Which, fair, but that’s the author’s problem. Writing docs is part of the job, table stakes stuff.
I mostly agree with your statement and I’m just nitpicking, but that document is not a source of truth if it has to be updated after the fact, it’s a reference.