Stay current with the latest in tech comm
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,000+ subscribers

Stitcher radio

Search results

Upcoming API Documentation Workshop in Mountain View, Calif., on August 30, 2019

by Tom Johnson on Jul 8, 2019 • 0 Comments
categories: api-doc

I'm giving an API Documentation Workshop in Mountain View, California, on August 30, 2019. Although I've given more than a dozen API documentation workshops at various conferences over the past several years, this one is different. For this workshop, I'm organizing it myself. You can register on Eventbrite.

Previous API workshops I’ve given have usually been by request through some organizing sponsor, such as STC group, private company, or conference. But I’ve come to wonder if that organizing group is even necessary, so I’ll just experiment at least once giving the workshop on my own, marketing it myself, setting up the venue myself, handling registration myself, etc. If it’s successful, I’ll repeat it regularly. And if it’s not, I’ll at least have more experience running an event.

Here are the details:

API Documentation Workshop

Title: API Documentation Workshop
Instructor: Tom Johnson
Date: August 30, 2019
Venue: Computer History Museum
Location: Mountain View, California
Time: 9am to 5pm
Cost: $399 before Aug 1, $499 after Aug 1

Here’s a description of the API documentation workshop:

API Documentation Workshop

REST APIs involve sending requests and receiving responses, not too unlike visiting a web page. You make a request to a resource stored on a server, and the server responds with the requested information. The protocol used to transport the data is HTTP. “REST” stands for Representational State Transfer.

In this workshop on writing documentation for REST APIs, instead of just talking about abstract concepts, I contextualize REST APIs with a direct, hands-on approach. You’ll first learn about API documentation by using a simple weather API to put a weather forecast on your site.

As you use the API, you’ll learn about endpoints, parameters, data types, authentication, curl, JSON, the command line, Chrome’s Developer Console, JavaScript, and more. Rather than learning about these concepts independent of any context, you learn them by immersing yourself in a real scenario using an API.

We’ll then transition into standards, tools, and specifications for REST APIs. You’ll learn about the most common sections in API documentation: resource descriptions, endpoints and methods, parameters, request examples, and response examples. We’ll also dive into specifications such as the OpenAPI specification and Swagger UI, which are commonly used for reference documentation. Exploring each of these sections will give you a solid understanding of how to document REST APIs.

You’ll also learn how to document the conceptual sections for an API, such as the getting started tutorial, status and error codes, authorization, sample apps and SDKs, code tutorials, and more. To gather insights here, you'll analyze examples of REST API documentation from various companies, inferring best practices and techniques.

Finally, we’ll dive into different ways to publish REST API documentation, exploring tools and specifications such as GitHub, Jekyll, and other docs-as-code approaches. You’ll learn how to leverage templates, build interactive API consoles so users can try out requests and see responses, and learn how to manage your content through version control.

You can access the course materials online at https://idratherbewriting.com/learnapidoc. On this site you can preview the course slides and the activities to get a better sense of the material. This workshop is open to anyone but is intended usually for the following types of people:

  • Professional technical writers looking to transition from GUI documentation into more API-focused documentation for developers.
  • Students learning how to prepare themselves technically to succeed in the tech comm field, which is becoming more focused on developer documentation.
  • Developers who are documenting their own APIs and want to know best practices for structure, terminology, and style with tech docs.

A full description of the event, including FAQ, is available on EventBrite. To register, go to EventBrite and click the Tickets button.

If you have any questions, just reach out to me at [email protected].

follow us in feedly