After decades of writing, reviewing, and — yes — reading a lot of API documentation, I've noticed that the same mistakes come up again and again. They're rarely caused by carelessness. They're usually caused by writers and teams who are too close to their own product to see it the way a stranger would.

Here are the five I see most often, and what to do instead.

1. Documenting for the team that built the product, not the developer who's new to it​

This is the most common mistake, and it's an easy trap to fall into.

When you work on a product every day, you stop noticing the things that are confusing to someone encountering it for the first time. The internal nickname for a core object becomes the name you use in the docs without explanation. The reason a certain endpoint works the way it does is obvious to you because you were in the room when the architecture decision was made — but it's completely opaque to an outside developer.

The fix is to put fresh eyes on your documentation regularly. Recruit someone who has never seen the API — ideally a developer, but even a non-technical colleague — and watch them try to complete a task using only your docs. The places where they get stuck are the places your documentation is failing.

Better yet, hire a technical writer who doesn't know your product. Not knowing it isn't a disadvantage — it's the qualification.

2. Burying the quickstart​

I have a personal rule when I'm evaluating API documentation: if I can't make a successful API call within ten minutes using only the docs, the documentation has failed.

Most developers approach a new API the same way. They're not starting with the reference docs. They're looking for the shortest possible path to "it works" — a moment of success that validates the integration is worth continuing.

If your quickstart is buried three levels deep in the navigation, requires the developer to read five conceptual sections before they get to a single line of code, or isn't present at all, you're losing developers before they've had a chance to see what your product can do.

The fix: make the quickstart the first thing in your navigation. Start with authentication and one working call. Get the developer to a successful response in under ten minutes. Save the deep conceptual material for later — they'll read it once they've already decided the API is worth their time.

3. Example responses that don't reflect real responses​

This one is subtle but corrosive to developer trust.

When a developer looks at your example response, they're building a mental model of what they'll receive in production. If that example is oversimplified, uses fields that don't actually appear in responses, or omits fields that the real response includes, the developer gets a wrong mental model. They write code against your example. Their code breaks in production. They lose trust in your documentation — and in your product.

I've seen this happen because a developer hand-wrote an example response without testing it against the actual API. I've seen it happen because the API changed and the documentation didn't. I've seen it happen because the example was written to be clean and readable rather than accurate.

The fix: example responses should come from actual API calls. Use a tool like Postman, copy a real response, anonymize any sensitive values, and use that. Automate the process if you can — some doc toolchains can generate examples from live API calls and keep them in sync with the actual responses.

4. Error documentation that tells you what happened but not what to do​

A developer who hits a 429 Too Many Requests error at 2am, with a production integration down, needs two things immediately: to understand what went wrong, and to know exactly what to do next.Most error documentation handles the first part reasonably well. It fails consistently at the second.

I've worked closely with engineers and developers throughout my career, and at two enterprise software companies — one focused on association management software, one on data integration tools. I was involved in creating the error handling documentation from the ground up — sitting with the engineering team to understand not just what each error meant, but what a developer would actually need to do when they encountered it. That experience shaped how I think about this problem.

"Rate limit exceeded" tells the developer what happened. It does not tell them what their rate limit is, how to check their current usage, whether the limit resets hourly or daily, what the Retry-After header value means, or how to implement an exponential backoff strategy. All of that is what they actually need.

The fix: for every error in your documentation, write at minimum: what the error means, the most common causes, and the recommended action. For rate limit and authentication errors specifically, include a code example showing how to handle the error gracefully. That code example will be copy-pasted into production by hundreds of developers. It's worth the ten minutes it takes to write it well.

5. Using "simple," "easy," and "just" — the three most dangerous words in API docs​

These three words have cost developers hours of frustrated debugging. I try to eliminate them entirely from any documentation I write.

"Simply add the Authorization header." Except it's not simple if you don't know what format the token needs to be in, where to get it, or how to handle the case where it expires.

"Just pass the user ID." Except the user ID is a UUID in some contexts and an integer in others, depending on how the account was created, and that's not obvious from the documentation.

"This is an easy integration." Except the developer reading this has been stuck for three hours and now they feel like the problem is their own competence rather than incomplete documentation.

The problem with these words is that they're written from the perspective of someone who already knows how to do the thing. They communicate confidence to the writer and condescension to the reader.

The fix: replace them with specificity. Instead of "simply add the Authorization header," write "Add an Authorization header with the value Bearer {your_api_key}, where {your_api_key} is the key from your dashboard under Settings > API Keys." That sentence takes three seconds longer to write and saves an untold number of support tickets.

A note on fixing these mistakes​

None of these problems require a documentation overhaul to fix. They require a fresh perspective and a commitment to writing for the reader rather than for yourself.

The most useful thing you can do right now: go to your own API documentation and try to complete a basic integration using only what's written there. Not using your memory. Not using internal tools. Just the documentation, the way a stranger would experience it.

What you find will tell you everything about where to start.

Haletha Judkins is a technical writer specializing in developer-facing documentation. She has been helping technical teams communicate more clearly since the 1990s — back when the internet was new enough that no one had figured out API docs yet either. Say hello here.

I'd been brought onto a project to document a new developer tool. I sat down with the lead engineer to go over the product, notebook open, ready to take down everything I needed. Forty-five minutes later, I had four pages of notes and understood approximately none of them. He spoke in acronyms I hadn't encountered, referenced internal systems by nickname, and assumed a baseline of knowledge I didn't have.

I left that meeting feeling completely out of my depth.

What I learned over the years that followed — and what I want to share with you here — is that the challenge of working with engineers isn't really a knowledge gap problem. It's a communication problem. And communication problems are fixable.

Understand how engineers think about documentation​

Before anything else, it helps to understand where documentation sits in an engineer's mental model of their work.

For most engineers, documentation is a tax, not an investment. It's something that has to happen after the real work is done, and it pulls them away from the thing they actually want to be doing. This isn't laziness or arrogance — it's a rational response to how engineering work is structured. Shipping code is what gets measured. Documentation usually isn't.

When you understand this, the way you approach an engineer for information shifts. You're not asking them to do something they value. You're asking them to spend time on something they find interruptive. The more you can minimize that interruption — coming prepared, asking precise questions, not scheduling a 90-minute meeting when a 15-minute Slack thread would do — the better your working relationship will be.

Do your homework before every conversation​

Nothing builds credibility with an engineer faster than showing up prepared. And nothing erodes it faster than asking questions you could have answered yourself.

Before any interview or review session, I read everything I can find: internal wikis, Confluence pages, Jira tickets, Swagger specs, GitHub READMEs, Slack threads if they're accessible. I'm not trying to become an expert before the conversation — I'm trying to understand enough to ask good questions.

Good questions are specific. "Can you explain how authentication works?" is a mediocre question. "The spec says the token expires after one hour — what happens if a user makes a request with an expired token? Does the API return a 401, or does it attempt to refresh automatically?" is a good question. The second version tells the engineer you've read the material, you're thinking about the developer experience, and you have a specific gap that only they can fill.

This approach has another benefit: it changes the dynamic. You stop being a writer who needs things explained and start being a colleague who is stress-testing the documentation. Engineers respect that framing.

Ask for examples, always​

Abstract explanations are the enemy of good documentation. When an engineer says "it handles the edge cases gracefully," your job is to find out what that actually means. My standard follow-up question is: "Can you show me an example?" or "What does that look like in practice?" Nine times out of ten, the example is more useful than the explanation — and it's what your readers need anyway.

This is especially important for error handling, edge cases, and parameter behavior. An engineer might describe a parameter as "controls the level of verbosity in the response" in a way that's technically accurate but tells a developer nothing useful. Ask them to show you a response at the lowest setting and the highest setting. Now you have something you can actually document.

Learn to read the code (a little)​

I want to be careful here, because I'm not suggesting technical writers need to become engineers. But there is a level of code literacy that makes you significantly more effective — and significantly more credible.

Specifically: being able to read a function signature, understand a basic JSON schema, and follow the flow of a simple script means you can often answer your own questions instead of scheduling another meeting. It means you can spot inconsistencies between the code and the documentation without an engineer pointing them out. And it means you can have a conversation about the API at a level that engineers respect.

I learned to read code through my college curriculum and, later, out of necessity — sitting with developers, asking them to walk me through what I was looking at, picking up languages through documentation projects. You don't need a computer science degree. You need enough to follow along.

Set up a documentation review process they'll actually use​

One of the most common failure modes I've seen is a documentation review process that engineers ignore because it asks too much of them. A Google Doc with comments is fine. A 45-minute review meeting for every doc page is not.

What works well:

A short, specific checklist for reviewers: "Is this technically accurate? Are there any missing parameters? Are the error codes correct?" Engineers can answer those questions in ten minutes. They cannot easily answer "Does this read well?"

A clear turnaround expectation. "I need your review by Friday" with a reason — "because this ships with the v2 launch" — is more likely to produce a timely response than an open-ended request.

Small review batches. Sending an engineer fifteen pages of documentation to review is how you get documentation that never gets reviewed. Send one section at a time, with specific questions.

Advocate for the reader, not yourself​

The most important thing I've learned in many years of working with subject matter experts is this: when there's tension about documentation content, the winning argument is almost never about writing quality. It's about the reader.

"I think this section needs more detail" is easy to dismiss. "A developer who hasn't seen this API before will get to this point and not know what to do next — here's what I think they need" is much harder to dismiss. You're not advocating for your own preferences. You're advocating for the person who will actually use the product.

Engineers generally care about their users. When you make the user's confusion visible and concrete, most engineers will engage with that seriously.

Build the relationship outside of documentation requests​

This one is simple and often overlooked: the best engineering relationships I've had were ones where I showed up before I needed something.

Attending sprint reviews. Reading the product changelog. Commenting on a GitHub discussion. Congratulating an engineer on a launch. None of these things take a lot of time, and all of them build the kind of goodwill that means your next review request gets prioritized instead of deprioritized.

Technical writers are often invisible in engineering organizations — we show up when we need information and disappear when we don't. The ones who build the strongest engineering relationships are the ones who don't disappear.

A final thought​

Working with engineers well is a skill that develops over time. It took me years to get comfortable in those conversations — to stop feeling like I was imposing and start feeling like I was contributing.

The thing that shifted it for me was realizing that good documentation is genuinely valuable to engineers, even if they don't always behave that way. Every support ticket that doesn't get filed because the docs were clear enough is time an engineer gets back. Every developer who successfully integrates without opening a GitHub issue is a win for the whole team.

When you can make that case — not in the abstract, but with specific examples from your own work — the relationship changes. You stop being the person who asks engineers for their time. You become the person who saves it.

Haletha Judkins has spent decades collaborating with engineers, product teams, and developers to produce documentation that actually gets used. She writes about technical writing craft, API documentation, and the art of translating complexity for human beings. Connect with her.

Let me break it down plainly, because I think once you understand what docs-as-code actually is, the question of whether you need it becomes a lot easier to answer.

What docs-as-code means, stripped of jargon​

The core idea is simple: write and manage your documentation the same way engineers write and manage code.

That means:

• Writing docs in plain text files (usually Markdown) instead of Word documents or proprietary CMS editors
• Storing those files in a version control system like Git, alongside or near the code they document
• Using the same review process for documentation changes that engineers use for code changes — pull requests, peer review, merge approvals
• Building and publishing the docs with automated tools rather than manually uploading files

That's really it. Docs-as-code isn't a specific tool or platform — it's a philosophy about how documentation should live and move through an organization.

Why it emerged​

Traditional documentation workflows have a fundamental problem: they're disconnected from the product.

When a developer ships a new API endpoint, the documentation for that endpoint usually goes through a completely separate process — routed to a technical writer, written in a CMS, reviewed by a different person, published on a separate timeline. By the time the doc is live, the code has already shipped. Sometimes the code has already changed again.

Docs-as-code tries to solve this disconnect by putting documentation inside the same workflow as the code. When a developer opens a pull request for a new feature, the documentation update is part of that same request. The reviewer reviews both together. The doc ships when the code ships.

The result, when it works well, is documentation that stays current — which is the single biggest complaint developers have about API docs.

The tools you'll encounter​

You don't need to learn all of these to get started, but here's what the docs-as-code toolset typically looks like:

Markdown is the writing format. It's plain text with simple syntax for headings, bold, code blocks, and links. If you've ever formatted a README on GitHub, you've written Markdown. The learning curve is about an afternoon.

Git is the version control system. It tracks every change to every file, lets multiple people work on the same content without overwriting each other, and maintains a complete history of what changed, when, and why. GitHub and GitLab are the platforms most teams use to host their Git repositories.

Static site generators turn your Markdown files into a published documentation website. The most common ones for API docs are MkDocs (Python-based, very approachable), Docusaurus (React-based, popular in the open source community), and Sphinx (the long-standing standard for Python projects). They all produce fast, searchable, professional-looking doc sites from plain text files.

CI/CD pipelines automate the publishing step. When a change is merged, the pipeline automatically builds and deploys the updated docs. No one has to manually push a publish button.

What it feels like to work in a docs-as-code environment​

I'll be candid — I'm working through this transition myself right now. But even at this early stage, the appeal is clear.

You write in a text editor instead of a CMS, which means you're not fighting with a WYSIWYG editor or waiting for a slow browser-based tool to load. Your files are local. You can write offline. You can use find-and-replace across an entire documentation set in seconds. You can see exactly what changed between two versions of a document as clearly as you can see what changed between two versions of code.

The collaboration model is also better for documentation quality. When docs live in Git, engineers can submit small corrections directly — a typo fix, an updated code sample — without routing it through a separate system. That means the documentation benefits from everyone's eyes, not just the writer's.

The learning curve is real but manageable. The two skills that take the most adjustment are Git (specifically the branching and pull request workflow) and Markdown (which takes a few hours to get comfortable with). Neither requires a programming background to learn.

Does your team actually need it?​

Here's my honest take: it depends on what you're building and how your team is structured.

You probably do need it if:

• You're building a developer-facing product with a public API
• Your documentation needs to stay in sync with fast-moving code
• You have engineers who want to contribute to documentation but find your current CMS cumbersome
• You're planning to build a documentation site that you own and control rather than relying on a hosted platform
• You want documentation to be part of your code review process

You might not need it yet if:

• You're a small team with a slow-moving product and a non-technical audience
• Your existing documentation process is working fine and the disruption of switching isn't worth it
• You're the only person maintaining the docs and a simpler tool serves you better

The honest version is that docs-as-code is the industry standard for developer-facing documentation, and if you're writing API docs professionally, knowing how it works is increasingly expected. That doesn't mean every project needs a full CI/CD pipeline and a custom Docusaurus site — but being comfortable in a Markdown-and-Git environment is now a baseline skill for API technical writers.

A practical starting point​

If you want to get comfortable with docs-as-code without committing to a full overhaul, here's a low-stakes way to start — and I mean this literally, because it's exactly what I did.

My practical starting point was migrating this site to Eleventy, a static site generator that runs on Node.js. Rather than setting up a separate practice project, I used my own portfolio as the learning environment. The stakes were real enough to keep me engaged, but the consequences of a mistake were low — worst case, my personal site looks broken for an afternoon.

The core workflow I learned through that process:

1. Write content in Markdown files.
2. Commit changes to a Git repository.
3. Let a static site generator (I used Eleventy; MkDocs is another good option) build the site from those files.
4. Push to GitHub and watch it deploy automatically via GitHub Actions.

That's it. That workflow — write Markdown, commit to Git, build with a static site generator, deploy automatically — is the heart of docs-as-code. The tools have different names depending on the company, but the pattern is the same everywhere.

If you want an even lower-stakes entry point before tackling a full site: create a free GitHub account, add a README.md to a new repository, and write something in Markdown. Make a change, commit it, and see how Git tracks the history. That single experience — seeing your changes version-controlled — is the mental shift that makes everything else click.

The bottom line​

Docs-as-code isn't magic, and it won't automatically make your documentation better. What it does is remove the friction between where code lives and where documentation lives — and in fast-moving developer product environments, that friction is the root cause of most documentation problems.

It's worth understanding, worth learning, and for most API documentation work, worth doing.

Haletha Judkins is a technical writer with decades of experience documenting complex developer products. She writes about API documentation, technical writing craft, and the changing Landscape of developer content. Connect with her here.

Here's what makes it different.

The output isn't deterministic​

With a traditional REST API, if you send the same request twice, you get the same response. That predictability is what makes example responses so useful in documentation. A reader can look at your sample JSON and say, "okay, I know exactly what I'm getting."

With an AI API — whether it's a language model, an image generator, or a speech-to-text service — the output varies. Sometimes significantly. Two identical requests to the same endpoint can return results that look completely different. How do you write an "Example Response" section for that?

The answer — and what separates good AI API docs from poor ones — is documenting the structure of the response, not just a single instance of it. You need to explain the range of what's possible, the factors that influence the output (temperature settings, system prompts, model version), and what "a good result" looks like versus an unexpected one. That's a fundamentally different writing task than documenting a payments API.

The parameters change the behavior in non-obvious ways​

Most API parameters are straightforward: pass currency: "USD" and you get USD. But AI API parameters interact with each other in ways that are genuinely complex to explain.

Take temperature in a language model API. You can explain the technical definition — it controls the randomness of the output, higher values produce more varied responses — but that doesn't tell a developer when to use 0.2 versus 0.8. For that, you need examples. Real, concrete, side-by-side examples that show what the output actually looks like at different settings.

The same goes for system prompts, stop sequences, context window limits, and the relationship between max_tokens and response quality. Each of these requires more than a one-line description. They require explanatory prose that helps a developer build an accurate mental model — and that's technical writing, not just parameter documentation.

The errors are probabilistic, not categorical​

With a traditional API, error documentation is relatively contained. A 401 means the token is bad. A 404 means the resource doesn't exist. A 422 means you sent malformed data. You can document these cleanly.

AI APIs have all of those errors, plus a class of "errors" that aren't HTTP errors at all: outputs that are technically valid responses but aren't what the developer wanted. A hallucinated fact. A truncated response. A refusal. A response in the wrong language. A code sample that doesn't compile.

These aren't failures you can handle with a try-catch block — they're behavioral patterns that developers need to anticipate and build around. Documenting them means writing content that doesn't fit neatly into a traditional error codes table. It might live in a "Known limitations" section, a "Best practices" guide, or inline callouts throughout the reference docs. Figuring out where it belongs requires the kind of information architecture judgment that separates a technical writer from a documentation template.

The audience is often two people at once​

AI API documentation often has to serve two very different readers: the engineer who is wiring up the API call, and the product manager or ML practitioner who is deciding what parameters to use, how to craft prompts, and what quality thresholds to set.

A pure reference doc serves the engineer. A pure conceptual guide serves the PM. But in practice, AI API docs need to do both — often on the same page — without alienating either reader.

Threading that needle requires a clear information architecture and a writer who understands both audiences well. The documentation that fails to serve AI API users most often fails at this level — written for one reader, accidentally ignoring the other.

So what does good AI API documentation actually look like?​

It looks like this:

Conceptual foundation first. Before any endpoint reference, readers need to understand how the model works at a high level — what it takes as input, what it produces, and what factors influence the output. A two-page "How it works" section saves ten support tickets.

Parameter documentation with behavioral examples. Not just type and description, but concrete before-and-after examples showing what changes when you adjust a parameter. Screenshots, sample outputs, even tables comparing outputs at different settings.

Honest limitations documentation. The best AI API docs don't hide the product's limitations — they document them clearly, with guidance on how to work around them. This builds developer trust far more than pretending the limitations don't exist.

Prompt engineering guidance. For LLM APIs especially, how you craft the input matters enormously. The best doc sets include a prompt engineering guide that teaches developers to get better outputs — not as a workaround for poor documentation, but as a genuine part of the developer experience.

Version and model change logs. AI models get updated, and updates can change behavior in ways that break integrations. A detailed changelog that explains behavioral changes — not just "performance improvements" — is essential.

Why this matters for technical writers right now​

After many years in technical writing, I find AI API documentation to be one of the most genuinely interesting documentation problems facing our field right now. The frameworks we've relied on for decades — the endpoint reference, the parameter table, the example response — are necessary but no longer sufficient.

The writers who figure out how to document probabilistic systems, explain behavioral parameters, and serve dual audiences on the same page will be the ones companies are looking for as AI products continue to proliferate.

If your team is building an AI product and struggling with the docs, I'd love to talk. The problems described here are solvable — they just require the right approach.

Haletha Judkins is a technical writer specializing in API documentation for developer audiences. Get in touch.

After years of maintaining my Words & Tech blog at Wordpress, I'm moving it here to haletha.com, where it belongs. Everything in one place, under one roof.

What this blog is about​

I write about technical writing craft, API documentation, working with engineers, and the practical realities of doing this work at a high level. Lately that means a lot of writing about AI — not in a hype-driven way, but in a "here's what actually works and what doesn't" way.

My background spans end-user documentation, developer documentation, API reference docs, content strategy, and more recently, automation and AI-assisted workflows. I've worked across industries, managed complex documentation projects simultaneously, and spent a career learning to speak to both developer and non-technical audiences without losing either one.

If you work at the intersection of language and technology — as a technical writer, developer advocate, content strategist, or engineer who ends up writing your own docs — there will be something here for you.

Already published​

If you're new here, start with these:

• Why AI APIs Are the Hardest Things to Document
• What Is Docs-as-Code — And Does Your Team Actually Need It?
• The Technical Writer's Survival Guide to Working with Engineers

More on the way. Thanks for being here.

About the Author​

Haletha Judkins is a Senior Technical Writer and Reader's Advocate who specializes in API documentation, user documentation, compliance reporting, and documentation automation.