Quick Answer: Elite software teams treat documentation as a first-class citizen. API specs and inline comments are just as vital as the code itself. Without explaining the "why" and "how," I've seen teams frustrate human users, confuse AI agents, and rely on fragile oral histories that break the moment a colleague leaves.
I look at a lot of codebases, and the defining trait of a truly elite software team isn't just the code they write—it's how they treat their documentation. The best teams treat documentation as a first-class citizen. The API specs you write and the comments scattered throughout your files are fundamentally as important as the logic itself. If you only write code, your software is only half-finished.
Why should developers treat API documentation as code?
Treating API documentation as code ensures your software is actually usable. If you only document paths and schemas without the surrounding context, I can almost guarantee developers will either abandon your API entirely or use it incorrectly and flood your queue with support tickets.
It is not enough to just list the endpoints, inputs, and outputs. A good API spec needs extra flavor. I always look for specs that answer: What is happening here? Why is it happening? How should I actually use this in a workflow? Imagine your team is building a fintech application. If you hand over a raw schema without explaining the specific sequence of calls required to clear a transaction, the integrating developer is going to be completely lost.
Generating the baseline boilerplate is usually pretty easy. There are plenty of deterministic tools that sit within your codebase and spit out the foundation. But your job is to add the flavor and context on top of that baseline.
Why is the "oral history" of a codebase dangerous?
Relying on oral history means the reasons behind weird technical decisions only exist in the minds of your teammates. If those colleagues get sick, go on vacation, or leave the company, that context disappears instantly.
I constantly see teams operating on this concept of an oral history to pass down knowledge. You open up a piece of code, spot something bizarre, and ask the person next to you why it was built that way. They'll usually say something like, "Oh yeah, we have to do that because the payment processor has a really awkward way of dealing with input," or "That engineer really wanted to try a wacky framework and we haven't had a chance to refactor it yet."
If none of that context is in the code, you are flying blind the second that colleague is unavailable. This is exactly why I advocate that inline code comments must describe the why, not the how. The code already explains the execution steps. Your comments need to capture that oral history before it walks out the door.
// BAD: Explaining the "how"
const activeUsers = users.filter(u => u.id !== 9999);
// GOOD: Explaining the "why"
// ID 9999 is a hardcoded test account used by the legacy payment
// processor. It must be excluded from daily billing batches.
const activeUsers = users.filter(u => u.id !== 9999);
How do AI agents change the way we write documentation?
Humans are no longer the only consumers of your APIs and codebases. AI agents are increasingly interacting with your software, and they rely entirely on rich context and descriptive comments to figure out how to execute tasks accurately.
Giving an agent a naked API schema is like giving someone a steering wheel without the car. If a human struggles to infer the purpose of an undocumented endpoint, an agent will completely fail. They need all of this context explicitly written out to be able to actually use your software.
To make sure your software is ready for both humans and agents, I recommend structuring your documentation with a mix of structural and contextual data:
- Base Schemas: Deterministic definitions of paths, inputs, and outputs (easily generated by tools).
- Workflow Context: Explanations of how endpoints chain together to achieve a real business goal.
- The "Why" Behind the "How": Inline comments explaining bizarre constraints, technical debt, or external system quirks.
- Semantic Instructions: Plain-text descriptions specifically designed to help LLMs understand the exact purpose of a function.
Frequently Asked Questions
Tools like Swagger, Redoc, and tsoa can automatically generate baseline deterministic documentation directly from your code annotations. These handle the schemas, but you still need to manually add the contextual explanations. Without your added flavor, the auto-generated docs are rarely enough for complex integrations.
Stop describing what the syntax is doing and start focusing on the business logic constraints. Instead of writing a comment that says you are looping through an array, explain that you are batching the payload because a downstream service drops requests larger than 5MB. If the comment just translates the code into English, delete it.
Do AI agents actually read API endpoint descriptions?
Yes, agents rely heavily on the textual descriptions attached to your endpoints and functions. When using LLMs for tool calling or orchestration, the descriptions you provide directly dictate whether the agent chooses the right tool for the job. Detailed, context-heavy descriptions dramatically reduce agent errors.
