So You Have to Document a REST API...Now What?

Join The Content Wrangler for a one-day intensive workshop for technical communicators on documenting REST APIs. Our instructor, technical communication expert, Tom Johnson, will lead the class.

Workshop schedule

8:30 - 9:00 am Breakfast, introductions
9:00 am - 12 noon — Morning session

• Part I: Introduction to API Documentation

• Part II: OpenAPI and Swagger

12 noon - 1:00 pm — Lunch

1:00 - 4:00 pm: Afternoon session

• Part III: Non-reference Content in API Documentation

• Part IV: Publishing API Documentation

4:00 - 5:00 pm: Optional 1:1 consultations with the instructor

What you must bring to participate

Each student must bring with them a fully-charged Windows or Macintosh laptop computer loaded in advance with the software needed to complete this workshop. See "Software installation requirements and laptop preparation" below.

NOTE: While there will be access to electricity at the venue, the instructor would like all students to show up to class with a fully-charged laptop to prevent unnecessary laptop charging delays that might prevent the student from completing the course in the time allotted.

Software installation requirements and laptop preparation

Here are a few things you’ll need to do before you arrive at the workshop venue:

• Pack your fully charged laptop and electric charging cable

• Download and install a text editor (Atom editor or Sublime Text are good options, and they work on both Macintosh and Windows)

• Download and install the Chrome web browser. Chrome provides a Javascript Console that works well for inspecting JSON, so we’ll be using this browser. (Alternately, Firefox works well too, if you prefer that web browser)

• Download and install Postman — an app that allows you to make requests and see responses through a GUI client

• Download and install curl — a tool for making requests to endpoints from the command line. Macintosh computers already have curl installed. Windows computer users should follow the instructions for installing curl here
  

• Download, install, and configure Git — a version control tool developers often use to collaborate on code. See Set Up Git
  

• Create (and be able to login to your) a GitHub account — to be used for various activities during the workshop. GitHub is commonly used as an authentication service for developer tools.

• Download and install Stoplight — an app that provides visual modeling tools for working with the OpenAPI specification. Create a Stoplight account using your GitHub credentials.
  
  

About the instructor

Tom Johnson is a technical writer in San Jose, California, mostly writing developer documentation, including documentation for APIs. He works at Amazon in the Appstore group, focusing on third-party development of apps on Amazon's devices (like Fire TV and tablets). Tom's main interest is focusing on how to simplify complexity. His main strategies for simplification involve enabling movement between macro and micro modes (such as through workflow and task maps), aligning with industry language and defining terms, abstracting away potentially unnecessary or advanced information from first-level views, and more.

Tom is the producer of the I'd Rather Be Writing blog and the author of a forthcoming book on API documentation.

You can contact Tom here.

Commonly asked questions

How can I contact the organizer if I have a question or concern?

If you have questions about the workshop that aren't addressed here, let us know.

What's the refund policy?

No refunds. In the event that you cannot attend the event, you must alert the organizers in writing before the event start date. In most cases, you will be allowed to send someone else in your place or we will issue you a credit you may use to attend a future The Content Wrangler event.

Where can I find directions to the venue?

Directions to the Quadrus Center are available here.