Search results

Workshop -- agenda, slides, activities

Last updated: Dec 27, 2021

Download PDF

The workshop agenda, slides, and activities correspond to full-day API workshop. The slides and activities mirror similar sections in the course.

Note that for API workshops, it helps to consolidate activities into a single page with brief instructions. The content for the activities below is the same content that appears in other parts of the course — it’s just pulled in here (single-sourced) for convenience. Workshops require a healthy amount of hands-on activities to be engaging. If you have feedback about how to improve the activities, or places where you keep getting stuck, let me know.

Not all activities in this course are consolidated here, since participants can only do so much during a workshop. The following activities are those I’ve selected for workshops.

8:00 - 9:00am: Registration + breakfast

Doors open at 8:00am. Check your name off at the registration table and get a name tag. Light breakfast (coffee and pastries) will be available. Find a table and get situated and acquainted with others. If you didn’t finish all the pre-workshop tasks as described in What You’ll Need, do that now.

9:00 - 9:30am: Intro to API documentation

Section: Introduction to API documentation

Activity 1: Identify your goals

9:30 - 10:15am: Using an API like a Developer

Section: Using an API like a developer

Activity: Explore OpenWeatherMap API

Activity: Get an OpenWeatherMap API key

Activity: Make requests with Postman

Activity: Make the OpenWeatherAPI request using curl

Activity: Make an API request on a web page

10:15 - 10:30am: Break

Break time

10:30 - 11:30pm: API endpoints

Section: Documenting API endpoints

Activity: What’s wrong with this API reference topic

Activity: Evaluate API ref docs to identify core elements

11:30 - 12:30: OpenAPI and Swagger

Section: OpenAPI and Swagger

Activity: Explore Swagger UI through the Petstore Demo

Activity: Create an OpenAPI specification using Stoplight Studio

12:30 - 1:30pm: Lunch

Lunch provided through catering.

1:30 - 2:00pm: OpenAPI and Swagger (continued)

Activity: Use Redoc Community Edition to render OpenAPI spec

Activity: Create a Swagger UI display with an OpenAPI spec document

2:00 - 2:30pm: Conceptual topics

Section: Conceptual topics

Activity: Complete the SendGrid Getting Started tutorial

Activity: Judge conceptual content and decide which is best

2:30 - 2:45pm: Break

Break. Snacks provided.

2:45 - 3:30pm: Code tutorials

Section: Code tutorials

Activity: Analyze two code tutorials

3:30 - 4:15pm: Publishing API docs

Section: Publishing API Documentation

Activity: Create a GitHub wiki and publish content on a sample page

Activity: Clone your GitHub repo locally

Activity: Push local changes to the remote

4:00 - 4:30: Participant’s challenges surfaced and discussed

During this time, I’d like to have participants surface specific challenges that they are facing and address them as a whole.

4:30 - 5:00pm: Thriving in the API doc space

Section: Thriving in the API doc space


This is a jeopardy game to test your learning. To play jeopardy, you’re given an answer. You have to supply the question. For example, if the answer is “a device on your wall that shows the time,” the question might be, “What is a clock?”


An authorization method for API requests that uses a third-party identity server such as Google, GitHub, or Facebook.

A tool you can use to submit API requests directly from the command line.

A GUI tool that lets you save and organize API requests into collections.

A format that includes both objects and arrays, and often a mix of both.

A space-sensitive format that is commonly used to write the OpenAPI specification.

The four most common methods or operations used with API requests.

The five common sections every API reference topic usually has.

A description of all possible elements in a response, including their data types and other details.

The object within the OpenAPI specification that lets you store re-usable content that can be referenced in other parts of the specification document using $ref.

The original name of the OpenAPI specification.

An authoring and validation tool useful when creating OpenAPI specification files.

A design model where you create the OpenAPI specification first before beginning any coding.

Information about request thresholds and what happens when you exceed them.

An open-source web framework that renders OpenAPI specification documents into an interactive documentation experience.

Authoring and publishing tools/workflows that follow similar patterns as software development tools and workflows.

A request to merge a branch back into the master; this workflow is often used when merging contributions back in to GitHub projects.

The tendency for docs maintained outside of code repositories to become out of sync with the code.

An essential first steps document for users that should usually be linked from your product overview page.

The go-to place to find open-source projects and collaborate with others on code projects.

A number shown in an API response when a request either succeeds or fails.

A parameter that appears in the resource URL after a question mark.

A string often included in a header or query string parameter that authorizes the API request.

The premium version of Swagger Editor.

A GUI tool for designing OpenAPI specification files, including the ability to auto-generate the schema description for JSON.

Programmatically building documentation from the server when you commit to a particular Git branch.

A web service API format, based on XML, that was popular before REST took over the landscape.

A type of API that consists of libraries or other code that you download and incorporate directly into your project.

Tooling that supports the implemention of an API in a specific programming language.

A parameter that appears directly in the resource URL (before any query strings).

You can find the answer key here.

5:00 - 5:30pm: Individual consulting

The general workshop ends and we transition into any individual consulting as desired. If you have specific questions not addressed during the workshop, let’s chat specifically about them. For all those interested, I’ll write your name on then board and then just meet with you individually for about 5 minutes each until everyone’s questions are answered.

About Tom Johnson

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.

6% Complete

6/165 pages complete. Only 159 more pages to go.