Course overview
- Overview
- Course introduction
- Why I developed this course
- About the author
- Download PDFs
- Workshop video recordings
- Workshop agenda, slides, activities
- What's new
Topic 1 of 8
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.
The 17 chapters
The course runs roughly in the order below, moving from what REST APIs are, through hands-on work with a real API, into reference documentation, publishing, and the working life of an API technical writer. You don’t have to read it straight through — each chapter stands on its own, so jump to whatever you need.
- Chapter 1 Introduction to REST APIs What REST APIs are, how they differ from SOAP, and why documentation matters so much here. 5 topics
- Chapter 2 Using an API like a developer Get API keys, make requests with curl and Postman, and work with the JSON that comes back. 12 topics
- Chapter 3 Documenting API endpoints The five sections of reference documentation, from resource descriptions to response schemas. 11 topics
- Chapter 4 OpenAPI spec and generated reference docs Describe your API with OpenAPI, then publish it using Stoplight, Swagger UI, or Redocly. 12 topics
- Chapter 5 Step-by-step OpenAPI code tutorial Hand-code an OpenAPI specification object by object, using the Swagger Editor. 13 topics
- Chapter 6 Testing API docs Test your documentation against the real API so the instructions actually work. 6 topics
- Chapter 7 Conceptual topics in API docs Overviews, getting-started guides, authentication, status codes, rate limits, and glossaries. 12 topics
- Chapter 8 Code tutorials Approaches for documenting code samples and tutorials — the hardest part for non-engineers. 10 topics
- Chapter 9 The writing process Planning, interviewing engineers, drafting, reviewing, and shipping developer documentation. 7 topics
- Chapter 10 Publishing API docs Structure, templates, branding, and the conventions that make developers trust your docs. 11 topics
- Chapter 11 Publishing tools Docs-as-code workflows using Git, GitHub, Jekyll, and other publishing toolchains. 8 topics
- Chapter 12 Thriving in the API doc space Getting hired: the coding familiarity, portfolio, and writing samples employers look for. 6 topics
- Chapter 13 Library-based APIs Documenting Java and C++ libraries that developers compile in rather than call over the web. 10 topics
- Chapter 14 Processes and methodology Managing doc work with Scrum-like processes, bug tracking, and review workflows. 15 topics
- Chapter 15 Metrics and measurement Measuring documentation quality and tracking improvement in ways management believes. 5 topics
- Chapter 16 Glossary More than 130 defined terms spanning API concepts, tooling, and documentation practice. 3 topics
- Chapter 17 Additional resources Supplementary material: GraphQL, RAML, API Blueprint, and topics beyond the core course. 13 topics
About this section
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.