It comes wrapped in unfamiliar tools, developer terminology, authentication workflows, JSON payloads, command-line examples, and enough Swagger-related vocabulary to make a sane person consider a career in artisanal candle making. But the truth is simpler: API documentation is learnable.

What most writers need is not magic 🪄. They need structured guidance, real examples, hands-on practice, and a chance to connect the abstract parts of API work to the documentation skills they already have.

That is why the Mastering API Documentation course from Docs Geek and The Content Wrangler looks worth serious consideration for tech writers who want to strengthen their skills and expand their value.

Learn More

The course is a 7-week live virtual class designed for technical communicators transitioning from UI to API writing, as well as developers, product managers, support specialists, and others who need to understand or document APIs. Each session runs about 90 minutes, for a total of 10.5 hours of classroom learning, plus 8 or more hours of offline exercises.

What Makes This API Docs Class So Valuable?

What makes this workshop especially appealing is that it doesn’t stop at theory. The course includes live instruction, hands-on assignments, a final quiz, and a final project in which participants create and submit an API documentation portal for peer review. By the end, students are expected to produce a complete documentation portal and get guidance on publishing it as a portfolio piece.

That matters. Learning is good. Leaving with something you can show to an employer or client is better.

What Does The Curriculum Include?

The curriculum also looks thoughtfully built for technical writers who want a practical ramp into API work. It starts with API basics and moves into JSON, Swagger UI, Postman, OpenAPI, YAML, Curl, authentication, query parameters, API flows, Mermaid diagrams, sequence diagramming, and refining API references.

In other words, it does not just explain what APIs are. It walks students through the tools, structures, and thinking patterns they need to do the work.

That learning progression is important because some of us aren’t actually starting from zero. We already know how to explain complicated things clearly. We already think about audience, structure, task flow, reuse, and precision. What we often lack is confidence with the tooling and the developer-facing context.

A course like this helps close that gap by showing how user journeys connect to API flows, how requests and responses behave, and how reference material should be written so developers can actually use it.

A Live, Instructor-Led Experience

Another strong selling point is that this is a live course, not just a pile of prerecorded videos abandoned in the digital wilderness. Participants get step-by-step joining instructions after purchase and access to a course Discord community for ongoing support and discussion. For many writers, that kind of interaction can make the difference between “I watched some lessons” and “I can now do this work.”

Classes Begin Soon — Don’t Delay!

There is also a practical reason not to sit on the decision too long. The Spring 2026 class registrations are open, the maximum student count is 30, and the sessions begin April 20, 2026, with weekly classes continuing through June 8, 2026.

If you have been thinking about moving from UI documentation into API documentation, or if you manage writers who need to build API skills, this workshop is a strong investment in capability. It is grounded, hands-on, and clearly designed to help people produce real work, not just collect new buzzwords for LinkedIn.

Use Our Discount Code To Save 💰

And here is one more reason to register now:

💰 Save 10% off the cost of registration when you use discount code — TCW — at checkout.

Register Today!

For those of us looking to become more versatile, more marketable, and more comfortable documenting modern software products, this is an incentive to stop circling the runway and finally get on the plane. 🤠

About the Instructor

Mark Wentowski is an API Documentation Specialist and senior technical writing consultant with more than a decade of experience helping software and SaaS companies create clear, effective developer documentation. His expertise includes API references, tutorials, conceptual guides, deployment and configuration content, and documentation strategy. As a consultant, speaker, and author focused on API-doc best practices, Mark brings both real-world experience and practical teaching insight to the workshop.

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

SmartBear makes testing tools to help developers and quality assurance pros deliver high-quality software products.

In this analogy, the kitchen is like a software program or an online service (e.g., weather data, social media). Sitting at the table, you are like another software program that wants to use the services or features of that program. The menu is like a list of the program's available functions and services. The waiter is an API, which stands for Application Programming Interface.

An API is like a middleman or messenger (like the waiter) that takes requests from you, communicates them to the program or service, and then brings back the response or the data you requested. This process is effective because it allows different software programs to talk to each other and work together without you knowing all the details about how the kitchen (or other programs) does its job.

In technical terms, a software program sends a request when it wants to use an API. This request is typically just a message formatted in a certain way (like placing an order from the menu). The API processes the request and talks to the program or service. Once the program or service acts on the request, the API returns the information or the confirmation of task completion.

APIs are essentially a set of rules and tools that allow different software applications to communicate and interact with each other, similar to how servers help you get food from the kitchen in a restaurant. In today's heavily digital world, APIs are used everywhere, from fetching weather data to logging in with social media accounts,  translating information from one language to another, and much more.