1. I'd Rather Be Writing
2. Docs
3. Course overview

Documenting APIs: A guide for technical writers and engineers

In this course on writing documentation for APIs, instead of just talking about abstract concepts, I contextualize APIs with a direct, hands-on approach. You’ll first learn about API documentation by using a simple weather API to put a weather forecast on your site.

As you use the API, you’ll learn about endpoints, parameters, data types, authentication, curl, JSON, the command line, Chrome’s Developer Console, JavaScript, and more. The idea is that rather than learning about these concepts independent of any context, you learn them by immersing yourself in a real scenario while using an API. Immersion in real scenarios makes these tools and technologies more meaningful.

We’ll then transition into standards, tools, and specifications for REST APIs. You’ll learn about the required sections in API documentation, analyze examples of REST API documentation from various companies, learn how to join an open-source project to get experience, and more.

• About REST APIs
• From practice to documentation
• Who the course is for
• Course organization
• Sequence and activities
• How long will it take to finish the course?
• Will this course help you get a job in API documentation?
• No programming skills required
• What you’ll need
• Testing Your Setup
• Video recordings
• Course slides
• Copyright and re-use of materials
• Is this course really free?
• PDF format
• Let me know if any content is out of date
• Stay updated
• Other resources

About REST APIs

In a nutshell, REST APIs (which are a type of web API) involve requests and responses, not too unlike visiting a web page. You make a request to a resource stored on a server, and the server responds with the requested information. The protocol used to transport the data is HTTP. “REST” stands for Representational State Transfer.

I dive more into the principles of REST in What is a REST API? In REST API documentation, you describe the various endpoints available, their methods, parameters, and other details, and you also document sample responses from the endpoints.

From practice to documentation

In this course, after you practice using an API like a developer, you’ll then shift perspectives and “become a technical writer” tasked with documenting a new endpoint that engineers added to an API. As a technical writer, you’ll tackle each element of a reference topic in REST API documentation:

1. Resource descriptions
2. Endpoints and methods
3. Parameters
4. Request example
5. Response example

Exploring each of these sections will give you a solid understanding of how to document REST APIs. You’ll also learn how to document the conceptual sections for an API, such as the getting started tutorial, product overview, status and error codes, request authorization, and more.

You’ll also dive into different ways to publish REST API documentation, exploring tools and specifications such as GitHub, static site generators like Jekyll, and other docs-as-code approaches. You’ll learn how to leverage templates, build interactive API consoles so users can try out requests and see responses, and learn how to manage your content through version control.

We’ll also dive into specifications such as the OpenAPI specification and Swagger UI (which provides tooling for the OpenAPI specification). Additionally, you’ll learn how to document native library APIs and generate Javadoc.

Tech writing is about more than tools and technology, though. As such, I even explore processes and methodologies in depth, explaining how to manage both large and small documentation projects, how to collect documentation feedback, how to keep stakeholders happy and updated, and more.

I’ve also included a section on metrics and measurement, which lists a comprehensive quality checklist. The criteria described can help you evaluate your own developer portal in myriad ways against industry best practices.

Throughout this course, I put these concepts in real, applicable contexts with hands-on activities and demos.

Who the course is for

The course primarily serves the following audiences:

• Professional technical writers looking to transition from traditional documentation into more API-focused documentation for developers.
• Students learning how to prepare themselves technically to succeed in the tech comm field, which is becoming more focused on developer documentation.
• Developers who are documenting their own APIs and want to know best practices for structure, terminology, and style with tech docs.
• Educators who are training technical writing students about API documentation practices and technologies.

Course organization

The course consists of the following sections:

• Course overview. This section provides a high-level, detailed overview for the API documentation course. I introduce the goals of the course, explain why I developed it, tell you a bit about myself, provide some recordings, slides, and more.

• Chapter 1: Introduction to REST APIs. REST APIs consist of requests and responses between clients and servers over the web. Although there are many types of APIs, REST APIs are flourishing, and there’s a strong need for API documentation at almost every company that provides an API. Technical writers can apply their skills to fill this gap in highly valuable ways. This introduction discusses different types of APIs, reasons for API growth, and why docs are critical for REST APIs. It outlines course contents, prerequisites, goals, and target audiences. The introduction sets the stage for learning API documentation through the hands-on activities in the course.

• Chapter 2: Using an API like a developer. In this chapter, you use a REST API like a developer would. You get API keys, make requests with Postman and curl, analyze JSON responses, and dynamically display API responses on a web page. These hands-on activities give you context for understanding developer needs and workflow. After using the API in this way, you switch perspectives and prepare to start documenting an API as a technical writer.

• Chapter 3: Documenting API endpoints. The bulk of API documentation focuses on the resources available (accessed through endpoints) and the data returned. API reference documentation usually includes five key sections for each resource: resource description, endpoints and methods to access the resource, parameters, request examples, and response examples and schemas. After learning about each section, you document a sample resource. You also evaluate and improve existing API reference topics.

• Chapter 4: OpenAPI spec and generated reference docs. The OpenAPI specification provides a standard way to describe REST APIs, and includes elements such as paths, operations, parameters, and schemas. Tools like Stoplight, Swagger UI, SwaggerHub, and Redocly can generate interactive API reference documentation from the OpenAPI spec. In this chapter, you follow a tutorial for using Stoplight, a visual editor, to create an OpenAPI specification file and publish the documentation. As you work with the OpenAPI spec, you learn about “spec-first development,” a philosophy of creating the spec before developers write API code, as well as other challenges, such as integrating the reference output and conceptual documentation in a seamless experience.

• Chapter 5: Step-by-step OpenAPI code tutorial. Whereas the previous chapter involved building and publishing OpenAPI specification using a visual editor (Stoplight), in this chapter you code the spec by hand following a step-by-step tutorial using the Swagger Editor. You populate each of the main objects in the OpenAPI spec: openapi, info, servers, paths, components, security, tags, and externalDocs. For each object, you can refer to code samples and see how the source maps to the documentation output. The goal is to gain familiarity with the OpenAPI objects and properties by building a valid OpenAPI file from scratch.

• Chapter 6: Testing API docs. Testing documentation against your APIs is critical for documentation quality. Fortunately, testing REST APIs and their responses tends involves less setup and expertise than testing library-based APIs like Java. Even so, to test your docs, you need to set up a test environment and get access to API keys or other resources. This will involve collaborating with QA teams. Your goal should be to walk through your instructions personally, making test calls and verifying the responses. You also should push back against any technical assumptions as you champion user needs. In short, testing docs means avoiding passively documenting what engineers say but rather actively validating as much as you can.

• Chapter 7: Conceptual topics in API docs. Conceptual topics that make up documentation include product overviews, getting started tutorials, authentication and authorization, status and error codes, rate limiting and thresholds, quick reference guides, glossaries, and best practices. These topics provide critical context for understanding and using the API beyond just the reference documentation. The chapter explores best practices for each topic, reasons why the topics are often neglected, and includes examples from API documentation sites. Activities guide you to evaluate these topics in an open source API project and decide which examples demonstrate best practices. The chapter emphasizes the importance of conceptual documentation in facilitating the user’s journey in understanding and adopting the API.

• Chapter 8: Code tutorials. Documenting code can be one of the most challenging aspects of API documentation, especially for non-engineers. Code can be hard to document because of its non-linear nature. For example,you don’t simply start by describing chunks of code from top to bottom. Figuring out your audience’s technical level can also be a guessing game, as a user’s proficiency in one language or area might not carry over to another. As you document code, focus on the “why” instead of the “how,” and consider building up complexity in stages, starting simple and expanding into more advanced use cases. If you can provide interactive browser experiences with code, which allows users to adjust the input and immediately see the output, this can also help developers learn.

• Chapter 9: The writing process. The five main steps in the documentation writing process include (1) Planning (creating a doc plan, establishing roles), (2) Gathering information (interviewing engineers, product managers, etc.), (3) Writing (separating content into groups, outlining, scheduling reviews, writing the first draft), (4) Reviewing (reaching out to the right people, incorporating feedback, resolving conflicts), and (5) Publishing (integrating new content, adding metadata, coordinating timing, publicizing releases). This chapter provides practical tips in each writing step, such as recording engineering interviews, bringing questions to review meetings, and publicizing releases through newsletters. Although many other aspects of API documentation might seem more pressing, such as configuring your publishing toolchain, writing is still a core task technical writers do when creating API documentation.

• Chapter 10: Publishing API docs. When you’re publishing API documentation, it’s important to have consistent structure and templates, ensure seamless branding, provide plenty of code samples, and follow other API documentation conventions. If you can include an interactive API explorer, users will love it. In this chapter, you dive into tools like Jekyll, Hugo, Sphinx, GitHub Pages, and ReadTheDocs for documentation. The chapter encourages you to embrace the docs-as-code approach, which means using static site generators, version control (Git), lightweight documentation syntax (Markdown), continuous integration, and more. Docs-as-code tools fit well into engineering workflows, making it easier for developers to contribute and review documentation.

• Chapter 11: Publishing tools. Publishing technical documentation typically involves following docs-as-code tools and workflows. For open source projects, GitHub is frequently used to manage content. But even within the enterprise, Git is still common. A typical documentation workflow involves making pull requests with doc changes that get rolled into the main branch. In this chapter, you explore some of these workflows using tools like GitHub wikis, Jekyll, CloudCannon, Oxygen XML and more. It’s important to become comfortable working from the command line to create branches, get updates, perform merges, and push builds.

• Chapter 12: Thriving in the API doc space. Getting a job in API documentation requires you to have some familiarity programming languages, experience writing developer docs, and a portfolio of writing samples. Chances are, hiring managers will want you to be tech savvy and comfortable working in code, with less to say about your actual writing skills. While opportunities for API documentation roles exist globally, tech hubs such as California, Texas, New York, and Virginia have a higher concentration of these jobs. If you need to build up a writing portfolio, consider contributing to open source projects and creating sample API reference documentation.

• Chapter 13: Library-based APIs. Library-based APIs are programming-language-specific APIs, such as Java and C++ libraries (instead of web APIs) that developers compile into their code instead of accessing via web protocols. If you’re documenting a library-based API, at least for the reference content, you add documentation in the form of code comments (following specific tags), and then build the output using tools like Javadoc (for Java) or Doxygen (for C++). Each library-based API has its own documentation generators that build from source and output documentation from comments in that source. Although working in the source code might seem uncomfortable at first, it’s essential to become familiar with these workflows if you want to contribute to the API’s reference documentation.

• Chapter 14: Processes and methodology. This chapter dives into project methodologies to manage technical documentation work. For both extensive projects and minor documentation requests, file the requests as bugs and managing them using a Scrum-like methodology, preferably following similar management processes as your engineers. You need to understand your engineering organization’s release cycle process and plug documentation into that cadence so that you can anticipate upcoming documentation needs and orchestrate reviews in time for the releases. Besides working on new requests, you also need a method for maintaining existing documentation and ensuring quality. From SDK releases to kickoff meetings and more, you need processes to follow. To facilitate communication, tech writers should be visible and participate in the activities, forums, and channels around them.

• Chapter 15: Metrics and measurement. Measuring API documentation quality and tracking its improvement is a frequent management request that’s challenging to fulfill. User surveys and satisfaction scores offer some insight, but they shouldn’t be the only evaluation tools. This chapter provides a comprehensive quality checklist for API documentation and developer portals, spanning more than 70 different aspects that involve accuracy, clarity, completeness, and relevance across your API documentation. This checklist can help highlight areas to focus on and be a springboard for discussion about ways to improve your developer portal. Although scoring methods are possible, your primary focus should be to agree on clear, actionable standards for documentation quality.

• Chapter 16: Glossary. This glossary provides definitions and explanations for over 130 key terms related to API documentation. The terms span a wide range of topics relevant to documenting REST APIs, including general API concepts, OpenAPI/Swagger specifics, API parameters, responses, methods, tools, project management approaches, writing best practices, and more. The terms are organized alphabetically as well as by common topic groups, allowing you to easily browse terms within certain subject areas.

• Chapter 17: Additional resources. Additional resources provides a variety of supplementary material to expand on topics covered in the course. This is also the section where content gets archived that no longer fits into the other chapters. There are several hands-on activities for calling additional APIs to get more practice working with endpoints, parameters, and responses. Tutorials are provided for two (semi-abanoned) API specification formats: RAML and API Blueprint. The chapter also contains answer keys for activities, as well as video recordings of previous workshops.

You can download a PDF of this course here. The download includes a comprehensive PDF of the entire course (900+ pages) as well as individual chapter PDFs, which are more practical for printing. The chapter PDFs are all under 10MB, which means you can also upload them into Claude.ai or other AI tools with large input allowances and interact with the information that way.

Sequence and activities

You don’t have to read the sections in order — feel free to skip around as you prefer. Some of the earlier sections (such as the section on Using a REST API like a developer and Documenting endpoints) follow a somewhat sequential order with the same weather API scenario, but by and large you can jump around as desired.

Because the purpose of the course is to help you learn, there are many activities that require hands-on coding and other exercises. Along with the learning activities, there are also conceptual deep dives, but the focus is always on learning by doing. Where there are hands-on activities, I typically include this icon in the section title: . Other topics have the word “Activity” in the title. The activities are integrated into various sections, but you can also see many of the activities in the Workshop Activities. These are the activities we do during live workshops.

Clear technical documentation, complex translation, and content operations

Manage API docs and software docs all in one place.

About Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.