In this section, we dive into the challenges of creating and maintaining API documentation. As APIs become an increasingly important and common part of many products, we asked how teams are overcoming those hurdles.
said their biggest challenge related to API docs is keeping everything up-to-date
don't use established frameworks, such as diátaxis, when structuring their documentation
Docs tooling and structure
The tools that teams rely on (besides AI, which we’ll come to later)
[Select all that apply]
When it comes to documentation, most teams rely on familiar tools. Version control platforms like GitHub and GitLab are by far the most common tools used to manage docs. A good number of teams also use analytics tools to track how people use their documentation.
How teams organize their documentation
[Select all that apply]
But when it comes to how teams organize their docs, most aren’t following a formal system. Around 77% of respondents said they use homegrown methods to structure information. Fewer than 1 in 4 use a framework like Diátaxis.
Is documentation all in one place — or scattered across platforms?
Most teams try to keep their documentation in one place, but it’s not always that simple.
About 75% of respondents said their docs are at least somewhat centralized. Half of those have everything in a single platform. But around 25% said their documentation is spread out across multiple platforms, which can make it harder for users to find what they need.
As products and teams grow, keeping docs organized and easy to access becomes a bigger challenge — especially when information is scattered.
API documentation
As software becomes increasingly interconnected, APIs are the glue that connects different apps, services, and platforms. And good API docs are key to making that work.
Do you use the OpenAPI specification?
Almost 74% of companies that offer APIs use the OpenAPI specification. This shows that using a standard way to describe and document APIs is now common practice, not just a nice-to-have.
The features teams want most in API docs
[Select all that apply]
Teams aren’t just writing static API docs anymore. They want documentation that keeps up with constant changes and helps users interact with APIs easily.
When we asked what features matter most in an API documentation platform, automation and interactivity were clear winners. Companies want their docs to update themselves when APIs change and to offer things like interactive “Try it out” options for developers.
Hardest challenges for API docs
The biggest headache for teams writing API docs? Keeping them up to date.
More than half of the people we surveyed said staying current is their top challenge. APIs change fast, and manually updating docs every time is tough — especially when products are shipping updates all the time.
That’s why so many teams are looking for ways to automate their API documentation. If your docs can automatically reflect changes in the API, you save time, avoid mistakes, and make life easier for developers.
How API documentation is changing over time
API documentation has become way more important over the past five years. Nearly 80% of respondents said it’s more important now than before — and over half said it’s much more important.
APIs are at the heart of modern software, so clear and helpful docs aren’t optional anymore — they’re critical.
How engineers and writers work together on API docs
In most companies, engineering teams take the lead on API docs. About 40% said engineers handle API documentation on their own, without help from technical writers.
While this works for some, it also means many teams might be missing out on what technical writers bring — like clearer language, better structure, and more helpful examples. There’s a big opportunity for engineers and writers to team up and make API docs better for everyone.
Strategic implications
Without automation, docs can't keep up with product velocity
Teams know they can’t rely on manual updates for API docs anymore. With APIs changing so often, keeping docs accurate by hand is a losing battle.
That’s why automation is becoming a must-have. More than half of the people we surveyed said their biggest challenge is keeping docs up to date — and they’re looking for tools that can handle updates automatically.
The goal is simple:
– Auto-generate baseline docs
– Catch API changes as they happen
– Let users test APIs right inside the documentation
With 74% of teams already using OpenAPI, many have the foundation to make automation work — they just need to put the right systems in place.
Engineering and docs teams must partner for better outcomes
Even though technical writers usually own documentation, API docs are a different story — most companies have engineers leading that work. In fact, 40% said their engineering teams handle API docs alone.
This gap is both a challenge and a big opportunity.
The best API docs happen when engineers and technical writers work together — combining technical accuracy with clear, user-friendly explanations and real-world examples.
Teams should:
– Define who owns what in API documentation
– Use both engineering know-how and writing skills
– Invest in tools that support both sides
When engineers and writers team up, API docs go from being a list of endpoints to a real resource that helps users succeed.
Docs have become core to product and business success
API docs aren’t just technical references anymore — they’re a key part of product strategy.
Nearly 80% of respondents said API documentation has become more important in the last five years. For many teams, if a tool has poor docs (or no docs), it’s immediately off the table.
More teams are treating docs like code — using GitHub, GitLab, and version control to manage updates properly. This “docs as code” approach helps keep things accurate and consistent, especially as APIs become central to partnerships, integrations, and developer adoption.
By organizing their docs, tracking how people use them, and making sure everything’s in one place (like 75% of teams already do), companies can turn documentation from a baseline necessity into something that actually drives growth and keeps users around.
Prev