An Engineering Manager’s Guide To API Reference Documentation
Make it make sense.
Imagine going to a restaurant that doesn’t have menus.
You arrive and wonder what they serve. It could be:
Thai
Portuguese
Indian
Or none of these
You can ask for a dish, and maybe they have it. If they don’t, you’re stuck in an endless back-and-forth with the waiter. Until eventually there is something you want, and the restaurant can prepare.
But the process is frustrating, slow, and often ends in disappointment. Engineers feel the same when they face undocumented APIs.
Just like a menu helps customers choose what to eat, API documentation helps developers connect systems. It shows them what’s available, how to ask for it, and what to expect. This makes their job easier and faster.
API reference documentation is more than just a guide. It's the bridge between developers and the tools they need to build. Clear documentation speeds up development, and reduces the reliance on direct developer support.
However, maintaining and improving API documentation comes with its own challenges.
Join my free meetings workshop!
Date: 5/27/2025
Time: 9AM PST/12PM EST/5PM UTC
If meetings are draining your time, energy, or team momentum – this is for you!
In this live workshop, I’ll be covering how to prepare, manage, and lead them.
Click the button to sign up:
Looking forward to seeing you there!
Why API Documentation is important
Think of receiving a complex machine without a manual. Yes, you could figure out how it works, but it would take time – maybe too much. It’s the same with undocumented APIs. Documentation helps by:
Making things clear: Well-documented APIs prevent confusion and simplify integrations. They state what each endpoint does, how to access them, and what information they provide.
Reducing reliance on developers: Without documentation, teams spend more time on knowledge transfer. Documentation helps by providing a reference that everyone can refer to.
Improving discoverability: Clear documentation helps users quickly find endpoints, parameters, and responses.
Why you should care about API documentation
If you’ve worked with APIs before, you know how poor documentation can slow things down. Think about missing examples or having to guess the response format. You ask around, and no one knows who wrote the thing in the first place.
API documentation (and documentation, in general) reflects culture. And as an engineering manager (EM), you shape it.
Today, AI tools are transforming documentation by extracting context and structure directly from source code.
Tools like OpenAPI generators or docstring parsers make it possible to automate the creation of reference docs and inline comments. Still, documentation needs to stay close to the code – whether through docstrings, annotations, or comments. It should be updated whenever the code changes, to stay accurate and easy to trust.
In practice, here's what that looks like:
Docstrings and comments: They’re written directly in the code, making it easy for AI tools to know what the code is doing without needing to look elsewhere.
Annotations or decorators: They describe inputs, outputs, or behavior, especially in typed languages or frameworks like FastAPI.
Version control: It ensures that any time a developer updates the code, they can also update the relevant documentation in the same commit or pull request.
Teams usually use CI/CD checks or code review practices to flag outdated or missing documentation when something changes.
If you treat docs as an afterthought, so will your team. They’ll disappear from the backlog if you never mention them in standups, meetings, or reviews. You don’t need to write them yourself. But you need to make space, support, and celebrate people who care about them.
Documentation doesn't need to be beautiful – it just needs to work
This means examples that run, requests that are tested, and errors that make sense. If someone says: “I don’t have time,” ask what other engineers lose when they hit broken documentation.
For documentation to work, it needs to be standardized. Imagine one engineer writing in Markdown. Another using Notion. A third sharing a Postman collection buried in a Slack thread.
You can build a process that’s easy to follow:
Pick one place: and store all API documentation
Use a shared format: it can be Markdown, OpenAPI, etc., this way, everyone speaks the same language
Define what “done” means: for example, including request/response examples, error codes, and version info
Make access easy: lost links or private folders should not be the default storage place
And most importantly, enforce it, but do it with care. Because when your docs are clear and consistent, your team can move faster.
Keeping APIs up to date: versioning and changes
The only constant in life is change, and APIs are no exception. They grow over time:
Features get updated
New functionalities are added
And old methods become outdated
Without a versioning plan, these updates can break existing integrations. Users who once relied on specific functionalities may now find their implementations broken.
This mainly applies to REST APIs, where versioning helps avoid breaking changes. But with GraphQL, for example, you usually don’t need versions because its strict schema lets you add new fields without breaking existing ones.
Imagine making an update that alters a critical endpoint. If it's not documented, users are left trying to make sense of a system that no longer fits their needs. Integrating the new version without errors becomes a domino effect of problems. And these can go far beyond the development team.
To avoid this, you can:
Use clear versioning: Like /v1 or /v2, to separate newer changes from stable releases.
Announce updates: Communicate in advance so teams have time to adapt.
Keep supporting older versions: When switching to a new one, keep the old version running. This helps avoid breaking things that already work.
Set a timeline for deprecations: For example, three months, to phase out outdated endpoints.
If you're planning to update an API, make sure to explain it clearly. Good docs help everyone understand what’s changing and why.
Choosing the right documentation tools
Effective API documentation is not about the chosen tool but what works for you and your team. Some teams build their own platforms to host docs. This lets them customize and control who can see what.
In general, the right tool will:
Make APIs easier to use
Help teams work faster
And keep everything up to date
Here are some steps to consider when figuring out what’s right for you.
1. Start with your API type
If you’re working with REST: Swagger (OpenAPI) is a good choice. It generates interactive docs straight from the code.
If you’re using GraphQL: GraphQL Playground makes exploring queries easier.
2. Think about integration
A good tool works with your CI/CD pipeline, keeping documentation in sync as the API evolves. It should also run smoothly across platforms so your team isn’t locked into a tool that slows them down.
3. Don't forget usability
Documentation needs to be easy to understand for anyone using the API. A clean interface and clear tutorials make a big difference.
4. Support is important
Consider using tools with active communities and frequent updates.
Whatever tool you choose, remember to prioritize what fits your workflow – not just what’s popular.
Making life easier for your team starts from day one
When a new engineer joins your team, there’s a lot they don’t know. They’re learning:
Systems
Workflows
Expectations
And the APIs they’ll work with
Think about it. If they need to build or connect something, but the API isn’t documented, what happens?
They ping another engineer. That engineer explains the endpoint. Then another question comes up. More messages. More interruptions. API reference documentation avoids that.
Instead of constant back-and-forth, new engineers learn on their own without needing to ask for help every step of the way.
It also builds confidence. Usually, new engineers don’t want to feel like they’re bothering teammates with “basic” questions. When documentation is clear, they can contribute faster.
Good documentation shows that your team values clarity and quality. That matters when someone’s deciding whether they’ve landed in the right place or not.
If you want to make onboarding more efficient, invest in strong API documentation.
Automation is great, but humans are still needed
Automating API documentation seems the way to go. But that’s not always the case.
Sometimes, automations can be more frustrating than beneficial:
Tools and styles can vary: Different languages and frameworks handle API docs in their own way. For example, Swagger works well for a REST API in Node.js, but in other setups, teams might prefer something more adjusted to their stack or workflow.
Limited customization: Automated tools follow predefined structures. Sometimes, you might need something more specific. If a tool doesn’t let you tailor documentation to your needs, it’s only solving half the problem.
Excess of detail: Auto-generated docs usually include every possible detail – sometimes too many. Searching for a simple string can be a frustrating task.
Need for human oversight: Automated tools help keep docs updated and tidy. But they still need people to check for quality and clarity.
Automation is useful, but it is not a standalone solution – yet. When used thoughtfully, automation supports us. But when we hand over too much, we risk losing clarity, context, and the trust robust documentation builds. The goal isn’t just efficiency – it’s usefulness. And that still takes a human touch.
The short version: treat API documentation with the importance it deserves
Great API documentation helps developers, but they also shape how your team works. As an EM, the state of your documentation says a lot about your team’s habits. Do you value clarity, reusability, and onboarding ease?
You’re not just writing docs – you’re setting culture. Good API docs are a leadership lever.
Here’s what that looks like in practice:
Prevent mess later: Document now. Missing details today turn into Slack threads, meetings, and broken features tomorrow.
Plan for change: APIs evolve. Your docs should too. This is especially important when you add or remove features.
Standardize versioning: Use clear paths (like /v1, /v2) and communicate changes early. Support older versions when needed.
Use the right tools: Swagger, GraphQL Playground, whatever fits. But make it easy to explore and contribute.
Automate where you can: Tie docs to your CI/CD pipeline. This way, they stay in sync with your code.
Make onboarding smooth. Clear docs mean fewer questions, faster ramp-up, and less stress all around.
Don’t leave it to chance: Inconsistencies and tool sprawl slow everyone down. Build a system, and own it.
Clear documentation reduces risk, builds confidence, and makes your team more efficient. And that’s not extra work – that’s part of the job.
Changes to Thriving In Engineering
Changes are coming to Thriving In Engineering, and I want to be upfront with you about that. Going forward, some weekly guides will only be completely available to paying subscribers. For example, starting May 23, 2025, I’ll be curating the most insightful and relevant posts from across Substack into a single, easy-to-digest guide every Friday.
But I want to be clear: free subscribers still get full access to free weekly guides, free workshops, the free subscriber resources page, and partial access to guides for paying subscribers.
Discounted subscriptions
Additionally, to say thank you to all of my loyal subscribers, I’m offering a limited-time 20% off all paid subscriptions. This will be available through the end of May 2025. For one year, you get full access to all live Q&As (next one is on 6/12/2025; signup will start after the free workshop on 5/27), eBooks, PDF guides, and all newsletter guides for 20% off.