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
- Conclusion
- 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
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
Activity: Explore Swagger UI through the Petstore Demo
Activity: Create an OpenAPI specification using Stoplight
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
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
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
Conclusion
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?”
Answers
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
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/166 pages complete. Only 160 more pages to go.