Why Does API Documentation Drift?

API Docs drift because software changes faster than every source describing it can be updated. Each update to a release introduces changes. An endpoint is added. Maybe a parameter changes or an software development kit (SDK) gains a convenience method. Our release notes might announce a new capability, while our tutorials and examples, are (maybe) updated later — or not at all.

These are typical situations and they rarely reflect poor documentation practices.

The information describing an API is often maintained in different repositories, formats, and is managed by different teams sometimes using differing approaches and tools. Small differences accumulate until the implementation, OpenAPI specification, SDKs, release notes, and published documentation no longer describe exactly the same product.

Many organizations don’t discover those inconsistencies until customers encounter and report them.

Read more

Does the format of documentation influence the quality of AI-generated code?

In Tokens Not Jokin’: How API Documentation Format Affects AI Code Generation, Grzetich reports findings from more than 21,000 integration tests examining how AI systems perform when working with APIs documented in different formats. The book compares approaches including OpenAPI, YAML, Markdown, and others, while also exploring token usage, testing methodologies, and AI evaluation techniques.

One finding immediately stands out. Documentation format appears to have a substantial impact on code generation outcomes, potentially greater than the choice of AI model itself.

Does API Documentation Format Affect AI Code Generation?

Yes, according to Grzetich’s research. The book presents evidence that documentation structure can significantly influence how effectively AI systems interpret APIs and generate working code. The findings suggest the way information is organized may matter as much as, or more than, the model consuming it.

Why Should Documentation Teams Care?

For years, documentation professionals have focused on helping human readers understand products and services. AI coding assistants have introduced a second audience.

Today, docs are often consumed by both software developers and AI systems. The same API reference that helps a developer build an integration may also be used by an AI assistant to generate code, explain implementation steps, or answer technical questions.

When documentation contains ambiguity, inconsistent terminology, or incomplete examples, AI systems consume those weaknesses along with everything else.

What Topics Does Tokens Not Jokin’ Cover?

The book examines:

• API documentation formats

• AI code generation performance

• Token consumption and efficiency

• Documentation designed for machine consumption

• Evaluation and testing methodologies

• AI acceptance testing

Rather than relying on opinion or isolated examples, the book focuses on measurement and repeatable testing. That approach makes it useful even for readers who remain skeptical of some of the conclusions.

What Does This Mean For The Future Of API Documentation?

The rise of AI-assisted development is changing how docs are used. Our technical documentation is no longer only a resource people consult when they need help. It’s increasingly becoming source material used by AI systems to generate answers, recommendations, explanations, and code.

As a result, familiar documentation concerns take on new importance. Information architecture, content structure, metadata, terminology management, examples, and consistency all become factors that may influence machine-generated outcomes.

Many documentation teams have been advocating for these practices for years. AI may provide new evidence supporting their value.

Should You Read This Book?

If your work involves API documentation, developer experience, structured content, content engineering, or AI-assisted software development, the answer is probably yes.

The book raises important questions that many organizations haven’t yet begun to think about asking. It also provides data that can help move our conversations beyond speculation about prompts and models and toward the information those systems consume and rely upon.

Whether the research ultimately reshapes industry practices remains to be seen. What seems harder to dispute is the underlying premise: documentation is becoming part of the AI development stack.

Understanding how AI systems interact with our docs is no longer a niche concern. It’s becoming part of the job. Our job.

Buy the book!

The challenge is that knowing how a system works is not the same thing as knowing how to explain it to someone who has never seen it before.

Most developer-authored API documentation does a good job describing the API itself. Endpoints are listed, parameters defined, response codes documented, and OpenAPI-generated reference material provides a reliable inventory of available functionality.

And, yet…

👉🏾 developers still open support tickets
👉🏾 Integrations still fail
👉🏾 New users search community forums and GitHub discussions looking for answers

If the documentation already contains the technical details, why does that happen?

The answer is that API consumers are usually trying to accomplish a task, not study an API.

Documenting An API vs Helping Someone Use It

When devs write docs, they often focus on describing what exists. Tech writers focus on helping users understand how to use it. Those are related goals, but they’re not the same thing.

Developers might document the parameters accepted by an endpoint and the structure of the response. Tech writers add context.

👉🏾 Why would someone use this endpoint?
👉🏾 What business problem does it solve?
👉🏾 What assumptions does it make?
👉🏾 What must happen before it can be used successfully?
👉🏾 How does it fit into a larger workflow?

Those questions become important when users are under pressure to put something to work. Most people reading API docs are trying to complete a project, meet a deadline, or troubleshoot a problem. They aren’t reading for curiosity. They’re looking for the fastest path from problem to solution.

Does Content Consistency Reduce Confusion?

Yes. Consistent terminology, formatting, and organization make content easier to understand because readers do not have to stop and figure out whether different words, labels, or patterns mean different things. When content is inconsistent, people spend more time interpreting the information and are more likely to misunderstand it. Consistency helps readers find information faster, understand it with less effort, and complete tasks with greater confidence.

Without editorial oversight, API documentation can become a patchwork quilt of styles, terminology, and assumptions. Tech writers help bring consistency to the entire documentation set.

One team may refer to a “user.” Another uses “customer” to refer to the same role. A third introduces an entirely different term. The meaning may be obvious to the people who built the system and selected the term they use, but it is far less obvious to someone encountering it for the first time.

Consistency isn’t cosmetic. When terminology shifts, readers begin wondering whether different words describe different things. Ambiguity slows comprehension, increases mistakes, and creates unnecessary support requests.

Tech writers help reduce that ambiguity by standardizing terminology, creating documentation patterns, enforcing structure, and aligning language across the documentation set. We spend time making sure information is presented consistently because consistency reduces the effort required to understand it.

Related reading: Recommendations for Reducing Ambiguity in Written Procedures

APIs Live Inside Workflows

Another difference is that tech writers tend to think in workflows rather than individual components.

Developers often document APIs one endpoint at a time. Readers, however, need to accomplish tasks that span multiple endpoints and systems. They need to authenticate, submit requests, handle errors, manage pagination, work around rate limits, and recover when something goes wrong.

Good technical documentation connects those activities into a coherent process instead of treating each endpoint as an isolated object.

The Happy Path Is Only The Beginning

Examples are another area where technical writers often improve the user experience. Developer-authored examples frequently illustrate ideal conditions: valid inputs, successful responses, and predictable outcomes. Real implementations are rarely that tidy.

Users need to understand what happens when permissions are missing, requests fail, data is malformed, or assumptions prove incorrect. They need guidance for troubleshooting and recovery, not just confirmation that the happy path works.

Asking Different Questions

Perhaps the most valuable contribution tech writers make is serving as advocates for users.

Developers naturally view systems from the inside out. They understand the architecture because they created it (well, they used to understand, before they started co-coding it with Claude).

Tech writers approach the same system from the outside in. We ask what a new user will find confusing, what knowledge is assumed but never stated, which prerequisites exist only as tribal knowledge, and where someone is most likely to encounter difficulty.

Those questions improve docs but they often improve products, too. Documentation reviews frequently reveal onboarding problems, workflow gaps, inconsistent terminology, confusing error messages, and design decisions that create friction for customers.

Is Technical Documentation Part Of The Developer Experience?

Yes, API Docs are a critical part of DevX. API Docs aren’t simply a technical inventory of endpoints and parameters. They’re part of the developer experience. Developers provide the technical foundation, while tech writers help transform that foundation into something people and machines can understand, adopt, and use successfully.

The API may already be documented. Our opportunity is to make it usable. 🤠

Classes start February 09, 2026 and run through March 23, 2026. You can save $250 USD off the cost of training when you use discount code — TCW — at checkout.

The schedule

This course is designed for technical communicators transitioning from UI to API writing and stakeholders needing to document or understand APIs. Relevant roles include technical writers, developers, product managers, and support specialists. You’ll learn the essential skills to write industry-standard API documentation, covering REST APIs, API design, development environments, and API testing tools.

You’ll also learn to chart API flows, create step-by-step recipes, and write effective API references, including get-started guides, code samples, and error-handling techniques.

Course overview

This online course offers in-depth training on API documentation, blending theory and practical application.

Key features include:

• Instructor-Led Classes: Gain insights into various aspects of APIs and documentation with live demonstrations, such as making API calls and documenting APIs.

• Hands-On Assignments: Complete assignments between classes to reinforce learning and apply new skills.

• Final Project: Create and submit an API documentation portal for peer review.

• Final Quiz: Test your understanding with a comprehensive quiz at the end of the course.

By the course’s conclusion, you’ll master API documentation principles, tools, and best practices that will allow you to create clear, industry-standard documentation, and to collaborate effectively with software developers.

What to expect after purchasing the course

After you purchase, you’ll receive an email with step-by-step instructions on joining the live classes and accessing the class Discord community for ongoing support and discussions.

Questions?

Feel free to contact the instructor at mark.wentowski@docsgeek.io

About the Instructor:

Mark Wentowski is a technical writing expert and consultant with over 12 years of experience making complex ideas easy to understand. He’s worked with startups to build strong documentation foundations that scale, and collaborated with clients in multi-national software companies as well as firms in industries like finance (think Open Banking, Payment Processing, and Trading), eCommerce, and more. Mark has teaches an API documentation course that reaches audiences across the globe.

A collection of advice for improving API Documentation curated from peer reviewed journals, other academic research, and articles written by technical documentation practiontioners.

• Exploration

• Understanding

• Practice

• Application

The researchers make several specific recommendations for organizing software documentation (like API Docs) based on these stages, adapting to different developer levels, and prioritizing content organization and maintenance to enhance the developer experience.

Here's a summary of their recommendations:

1. Organize documentation based on the developers’ information journey:
   
   Documentation should be structured to align with the distinct stages of the developers’ information journey: Exploration, Understanding, Practice, and Application. Each stage has different needs, from conceptual information and experience sharing to code examples and technical details. A well-structured documentation that aligns with these stages can significantly enhance efficiency and effectiveness.
   

2. Adapt Documentation to Different Learning Needs:
   
   Recognizing that junior and senior developers have varying habits and preferences, documentation should offer diverse learning aids, such as video tutorials for beginners and comprehensive, in-depth examples for more experienced developers. This approach helps in catering to the wide spectrum of developer experience levels.
   

3. Prioritize Basic Experience Dimensions in Documentation Design:
   
   Software developers say that for documentation to be of use to them it must be correct, clear, complete, and regularly updated. Moreover, incorporating interactive design elements like online code editors can significantly enhance the developer experience by facilitating immediate practice and application.
   

4. Integrate Marketing and Technical Communication:
   
   Software documentation serves as a vital link between technical and marketing communication. Effective SEO and integrating documentation with an online community make it easier for developers to quickly find solutions and share knowledge with others.

Other studies highlight the barriers that incomplete or incomprehensible documentation creates, leading developers to seek information from external sources like StackOverflow and blogs rather than official API documentation.

Researchers note that some software developers prioritize solving challenges and often avoid seeking a deeper understanding of the underlying software or API, which aligns with the notion that developers aim to efficiently resolve tasks without mastering the finer details. These findings shine a light on the importance of providing clear, concise, and task-oriented documentation to meet developers' needs effectively.

See also: What software developers want from API documentation and read the research this post summarizes.

Topics covered:

• Traditional vs. Task-Based API Docs:
  

  Examining standard content like API references and code samples and their limitations regarding ambiguity, navigation difficulties, and misalignment with user goals.
  

• Developer-Centricity:
  

  Tailoring docs to different developer types (systematic, opportunistic, pragmatic) and integrating concepts directly into task descriptions for better utility.
  

• Efficient Strategies:
  

  Implementing adequate redundancy, side-by-side content-code layouts, intuitive navigation, context-aware semantic search, and considering single-page docs to enhance user experience.
  

• Strategic Implications:

  Emphasizing the need for custom information architecture and exploring content strategies for developers and non-developer stakeholders.

Watch the Recording

About the presenter:

• Mark Wentowski helps API developers around the globe explain their solutions to various audiences. He primarily works with SaaS companies delivering web-based, developer-to-developer conceptual docs for web services (i.e., APIs), libraries, and other software products, including deployment and configuration guidance for IT and DevOps engineers, user guidance for data scientists and engineers, API and command references, tutorials, walkthroughs, sample apps, and best practices guides.

Join us January 11, 2024 for Coffee and Content with Tom Johnson, senior technical writer at Google, and the creator of the "I'd Rather Be Writing" blog. During this episode you can ask Johnson anything you'd like about managing API documentation projects.

Attendees will gain access to educational materials Johnson has created to help technical communication and software development pros better understand API Docs.

Register

On August 2, 2023 join Dawn Stevens, The Technical Documentation Wrangler, for a friendly chat with Dave Wilks, a senior technical writer at data protection and encryption firm, Keyavi. They'll discuss why it's a great idea for technical writers to enhance their skills by adding API Docs to their toolkit.

Dave explores niches in technical writing and has worked as a Technical Writer, API Writer, Content Designer, Content Strategist, and Product Manager for a digital onboarding tool.

Let's Talk Technical Documentation is brought to you by The Content Wrangler and Comtech Services and is sponsored by Heretto, a component content management system and content operations platform that technical content teams use to collaboratively author, maintain, and deliver personalized, structured content at scale.

Register

What type of non-information are we talking about?

Many professional developers are hindered by “boilerplate documentation that merely rehashes the name of the API method, bloats the presentation with derived information such as inherited members, or provides overly trivial examples,” observed researchers Walid Maalej and Martin P. Robillard. Documentation quality can be improved by detecting and removing non-information from API Docs.

⦾ Advice: Avoid the use of filler words, redundant phrases, or excessive elaboration without adding meaningful information. Use authoring assistance tools that can help you reduce verbosity and increase clarity and comprehension.

Non-information is unnecessary and can make your documentation challenging to read, comprehend, and navigate, potentially leading to information overload and making it more challenging for developers to extract the essential details they need from the documentation.

Improving API documentation can reduce disruptions in concentration and help keep devs in the zone.

”Eliminating a one-minute, documentation-induced distraction through improved documentation could save 15 minutes of lost software developer productivity and provide a more satisfying, and more profitable, development experience,” writes Robert Watson, a senior technical writer at Google.

For several decades, the format used to structure and present documentation for application programming interfaces (API Docs) has remained largely unchanged. While research on what developers think should be contained in API Docs has revealed a list of improvement suggestions, few studies have compared what information devs say they need to what information they actually use.

In Patterns of Knowledge in API Reference Documentation, researchers Walid Maalej and Martin P. Robillard, point out that there’s “no standard and a few conventions regarding the content of reference documentation,” calling the typical API reference documentation a “mixed bag of information items.”

There’s been little effort to develop evidence-informed best practices for organizing, categorizing, and structuring dev-focused docs, they say. That needs to change.

Maalej and Robillard evaluated several popular sets of API docs to discover what types of knowledge are commonly available and how that information is categorized (see Figure 1 — “Taxonomy of Knowledge Types for API Documentation”).

Their efforts resulted in the creation of a taxonomy that they say is:

• Reliable — the docs are organized to help different API docs users understand the type of information contained in each individual section

• Meaningful — the docs contain content of relevance to the task at hand

• Fine-grained — the docs provide more than a few high-level categories of knowledge

  
  Figure 1

  

  
  

⦾ Advice: Consider using the taxonomy in Figure 1 to evaluate the content of your existing docs, better organize them, and to detect and eliminate low-value content like non-information.

The design and presentation of Application Programming Interface documentation (API Docs) can pose obstacles for software developers when they try to use a new API. Creators of API Docs can improve the utility of documentation by following this advice from researchers examining how devs use API documentation.

Streamline access to pertinent information

Content organization

Arrange, structure, and format content based on categories that align with the functionality or content domain of the API rather than relying on categories that indicate the type of information presented.

⦾ Advice: Instead of copying the organizational structure and category labeling schemes many API documentation collections use — Samples, Concepts, API Reference, and Recipes, consider using categories with clear lables such as Shipment Handling, Address Handling, etc.

This guideline is an application of minimalist documentation.

Integrate conceptual information with associated tasks

Developers differ in how, whether, and when they use conceptual overviews, which systematically introduce crucial API concepts. Some devs rely on documentation to explain concepts, while others ignore conceptual overviews.

⦾ Advice: To reach each group of developers, don’t segregate conceptual content in a section dedicated to demystifying concepts. Instead, consider presenting conceptual information alongside the tasks or scenarios where knowledge of relevant concepts is needed.

Offer straightforward navigation and helpful search

The navigation should provide devs with clear indications of their location within the documentation and offer unambiguous cues about the context of the topic they’re exploring.

A powerful search that displays related content alongside query results is one of the best ways to ensure developers can locate the information they need. Search should be capable of traversing your content repositories and presenting a unified result that displays all related, relevant content.

⦾ Advice: If unable to provide top-notch search, consider presenting a version of the documentation that exists on a single page, instead of distributing the content across multiple, linked pages. Presenting docs on a single page allows devs to use command—F to trigger the on-page keyword search, a tool many software developers rely upon heavily.

Simplify the process of accessing the API

Understanding entry points is crucial for developer success when working with a new API. Entry points are where devs initially start to begin utilizing APIs effectively.

Provide clean, working code samples

The navigation should provide devs with clear indications of their location within the documentation and offer unambiguous cues about the context of the topic they’re exploring.

Developers rely on — and reuse — code samples in API documentation. Efficient code reuse relies on a clean sample (correct, clear, concise, maintainable, and easy to comprehend) devoid of extra, irrelevant, or invisible code introduced unintentionally while copying the code from its source. Some devs use examples as a starting point when working to solve an API implementation challenge.

⦾ Advice: Generate concise and readily usable code samples (complete and ready to be copied and pasted) that effectively showcase the intended usage of the API.
If using placeholders (referencing other code examples) to eliminate redundancy, reccognize that this approach may make it impossible for devs to reuse code via copy and paste quickly.

Provide relevant background knowledge

The importance of background knowledge in the initial learning process is well understood. Knowledge plays the most significant role in comprehension. It’s like mental velcro.

Relevant knowledge gives words places to stick and make sense, supporting understanding and propelling the reading process forward. The more a dev knows about a topic, the more likely they are to successfully comprehend information about it, compared to those devs with less experience.

⦾ Advice: API documentation should furnish background knowledge to aid developers without domain experience in putting an API to work. Like conceptual information, domain-specific background knowledge should be available when needed and seamlessly integrated with task descriptions and relevant usage scenarios.

Links concepts and their practical use in code

Devs must be able to determine how certain concepts correspond to elements within code. The presence of code elements embedded in API Docs that explain their purposes, usages, and mutual connections with others

⦾ Advice: When presenting conceptual information, utilize code examples that highlight and conceptualize connected elements in the code.

Support diverse development approaches

API documentation must accommodate the varying strategies developers employ when approaching a new API. Both the content and its presentation should cater to the needs of both opportunistic and systematic developers.

Devs with an opportunistic learning approach work intuitively and do not follow the processes and suggestions described in the [API] documentation. Instead, they access the documentation only to identify and copy a snippet of sample code, which they modify or extend.

Make it easy for devs to find, copy, and use code

⦾ Advice: Enrich documentation with clean code samples that are complete and comprehensive. Ensure code is clearly delinated from text, making it easier for devs to spot and copy code snippets. Consider using a table with a separate column in which to display code examples.

Indicate the difference between text and code

⦾ Advice: To enhance clarity and improve comprehension of API Docs, signaling techniques like color-coding should be utilized to emphasize code elements within the text and in code examples.

Integrate and reuse important information

⦾ Advice: To ensure understanding, present conceptual information redundantly. Integrate vital details into the text describing how to perform a task with the API. Incorporate concepts into the source code using code comments, helping to guarantee that even opportunistic developers, who may skip the text and focus on the code, will encounter and notice the necessary detail.

Make it easy and fast to put the API to work

⦾ Advice: Usually, developers who follow an opportunistic strategy aim to start their first task quickly. On the other hand, systematic developers tend to take their time to understand the API and then try out sample calls. To help both types of developers, use a documentation approach that focuses on action and simplicity, following the principles of minimalism.

It’s common for software developers to adopt a self-directed approach to learning new APIs. Research from Sillito and Begel (2013) shows that some developers do not attempt to learn the entire API. Still, instead, they focus on the parts they believe are relevant to the problem they are attempting to resolve, for instance, getting a particular API function to work.

Developers often use this same approach to identify workarounds when problems occur.

Sillito and Begel found that “the features of applications that developers want to build define the topics they need to learn and that many of these topics are unknown to the developers until they encounter issues with them as they learn to build their application.”

Devs seek information from sources other than the official API documentation

”The conscious goal of their learning was often only to learn as much as was needed to complete their immediate development goal. They could return to the topic later to gain a deeper understanding if and when it was needed. Subjects typically found learning resources online via web search. They were more often supported by the experiences and wisdom of development community members from their blog posts and answers in Q&A forums than by the platform owner’s official documentation.”

Meng, Steinhardt, and Schubert conducted an observational study of developers working to solve programming tasks involving an API. The results reveal differences regarding developer activities and documentation usage that a successful API documentation strategy must accommodate.

What the research uncovered

There is no single developer persona; therefore, there is no “one-size-fits-all” API Docs experience because developers use different approaches to their work. For example, some developers are less willing to read conceptual information, although not reading it often impacts their effectiveness.

Providing all developers with the same API documentation experience is a mistake.

In the January 2019 issue of Communication Design Quarterly, the peer-reviewed research publication of the Association for Computing Machinery Special Interest Group for Design of Communication, the researchers explore three information-seeking software developer personae and the approaches they use when looking for information to put a new API to work.

Three developer learning personae:

1. Systematic learners — those who seek to understand the API before they use it

2. Opportunistic learners — those who seek to get started as quickly as possible without first understanding the API or checking the documentation

3. Pragmatic learners — those who combine elements of both systematic and opportunistic approaches

Characteristics of systematic learners

Researchers Meng, Steinhardt, and Schubert found that devs with a systematic learning approach “wrote code defensively” and “tried to get a deeper understanding of a technology before using it.” These software coders prepared for their work by exploring the API and preparing their development environment before starting.

The researchers discovered some systematic developers started every task with a clean piece of code (located in the code examples section of the docs). Then they used examples (found on the Samples and Recipes pages and in the API reference) to modify the code they started with.

“They seemed to use a similar process to solve each task,” the researchers say. Systematic developers tend to form a hypothesis about the approach and (if needed) clarify terms or concepts they did not fully understand.

The researchers witnessed the devs "in the systematic group carefully “read sections of the documentation and code samples, and, in general, followed the processes and suggestions closely.”

Characteristics of opportunistic learners

Researchers Meng, Steinhardt, and Schubert found that devs with an opportunistic learning approach “worked more intuitively” and “did not follow the processes and suggestions described in the [API] documentation.” Instead, they accessed the documentation only to identify and copy a snippet of sample code, which they modified or extended.

The researchers described developers in the opportunistic group as “highly task-driven” and desiring “fast and direct access to the information.”

They observed that opportunistic devs “did not take the time to get a general overview of the API before starting the first task” and did not read most of the documentation. Instead, they “scanned” it, jumping from page to page without an apparent search strategy, seeming to “deliberately risk” making errors, resulting in their having to check the documentation to overcome errors.

Researchers Michael Meng, Stephanie Steinhardt, and Andreas Schubert understand how developers use documentation when working with a new API. They hypothesize that problems with API documentation are often related to usability; precisely, the content and structure of the docs do not “match the work habits and expectations of software developers.”

Through interviews and observational studies of working habits, the researchers discovered common learning goals and strategies software developers use, the information resources they turn to, and the quality criteria they apply to API documentation.

In Application Programming Interface Documentation: What Do Software Developers Want (2018 Journal of Technical Writing and Communication), the researchers show that developers initially try to “form a global understanding regarding the overall purpose and main features of an API, but then adopt either a concepts-oriented or a code-oriented learning strategy that API documentation both needs to address.”

In How Developers Use API Documentation: An Observation Study, Meng, Steinhardt, and Schubert examine which resources developers use to put a new API to work. The most often accessed content is the API Reference, followed by the Recipes page, they found.

The Recipes page (and the Samples page) are places where devs obtain code samples for use cases. Some devs use the Concepts page, but less so than other areas of the docs, especially those pages that contain code samples. In contrast, some developers (systematic learners) use the Concepts pages extensively.

1. Inconsistency in navigation — Inconsistent navigation causes some developers to conclude that the documentation is incomplete. Inconsistencies in navigational elements from page to page introduce confusion. Navigational difficulties occur when a developer wants to revisit previously accessed content but can’t figure out how to do so.

2. Inability to find information by browsing — Developers experience difficulties browsing for information, especially when encountering pages with vague labels that don't accurately describe the page's information. Unclear labels can hinder developers' ability to effectively understand and utilize the API by increasing their cognitive load. Unclear labels require additional mental energy to decipher the purpose and content of each page.

3. Lousy search — Some sets of API documentation do not provide search. Others offer a rudimentary — but less-than-useful — search that fails to help developers quickly find the information they need. While some developers rely on the built-in on-page search available in most web browsers, those searches may fail to prove useful because API documentation is often distributed over multiple web pages.

4. Dirty code samples — Developers rely on — and reuse — code samples in API documentation. Efficient reuse of code relies on the sample being clean (e.g., correct, clear, concise, maintainable, and easy to comprehend) and devoid of extra, irrelevant, or invisible code introduced unintentionally while copying the code from its source. Additionally, using placeholders (referencing other code examples) to eliminate redundancy makes it impossible for devs to reuse code via copy and paste quickly.

You may have been told that software developers don’t require formal documentation — or only tiny bits and pieces of information (sentence fragments will do) — and not to bother building an exceptional developer experience.

Software developers rely on technical documentation that helps them build software applications and use Software Development Kits (SDKs) and Application Programming Interfaces (APIs). These docs are intended for a technical audience and typically include programming, installation, setup instructions, technical specifications, API information, code examples, troubleshooting, and debugging procedures. They also may include other types of content — release notes, best practices, and guidelines.

Some leaders I've spoken with say that creating detailed technical documentation for developers is not worth investing time and resources. They mistakenly believe that developers do not require docs built with the same level of care as consumer-facing technical information because they assume that developers are already technically proficient and do not require the same level of explanation and guidance.

Despite beliefs to the contrary, research shows that quality criteria such as accuracy, completeness, and clarity are relevant to the software developer’s experience using API documentation. Putting a new API to work can be challenging. Developers say documentation insufficiencies constitute a significant factor.

That's where a Software Development Kit (SDK) comes in handy.

SDKs are collections of resources: software tools, libraries, documentation, and code samples. Done well, SDKs simplify and expedite the development of software applications adapted for a specific computing platform, framework, or programming language. SDKs assist developers in creating software more efficiently by providing pre-existing functionalities and interfaces.

What are the differences between and Application Programming Interface and a Software Development Kit?

Application Programming Interfaces (APIs) and Software Development Kits (SDHs) are tools that software devs use, but they do different things. While an API is a way for software programs to talk to each other and share information, an SDK (also known as a devkit) is a toolbox for building software, which can also include APIs.

See: 10 Best Practices for SDK Generation