Workshop -- agenda, slides, activities
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
- 9:00 - 9:30am: Intro to API documentation
- 9:30 - 10:15am: Using an API like a Developer
- 10:15 - 10:30am: Break
- 10:30 - 11:30pm: API endpoints
- 11:30 - 12:30: OpenAPI and Swagger
- 12:30 - 1:30pm: Lunch
- 1:30 - 2:00pm: OpenAPI and Swagger (continued)
- 2:00 - 2:30pm: Conceptual topics
- 2:30 - 2:45pm: Break
- 2:45 - 3:30pm: Code tutorials
- 3:30 - 4:15pm: Publishing API docs
- 4:00 - 4:30: Participant’s challenges surfaced and discussed
- 4:30 - 5:00pm: Thriving in the API doc space
- 5:00 - 5:30pm: Individual consulting
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
9:30 - 10:15am: Using an API like a Developer
10:15 - 10:30am: Break
10:30 - 11:30pm: API endpoints
11:30 - 12:30: OpenAPI and Swagger
12:30 - 1:30pm: Lunch
Lunch provided through catering.
1:30 - 2:00pm: OpenAPI and Swagger (continued)
2:00 - 2:30pm: Conceptual topics
2:30 - 2:45pm: Break
Break. Snacks provided.
2:45 - 3:30pm: Code tutorials
3:30 - 4:15pm: Publishing API docs
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
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
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
I'm a technical writer / API doc specialist based in the Seattle area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out my API documentation if you're looking for more info about that. If you're a technical writer and want to keep on top of the latest trends in the field, 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/176 pages complete. Only 170 more pages to go.