API Documentation Workshop

Tom Johnson is a technical writer, blogger, and podcaster based in Santa Clara, California. In addition to his blog,https://idratherbewriting.com, he has developed an extensive online course on Documenting REST APIs athttps://idratherbewriting.com/learnapidoc. Over the last decade, he has given more than100 presentationsat various events and he has taught more than a dozen API documentation workshops.

Tom Johnson, I'd Rather Be Writing

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 <A HREF="https://idratherbewriting.com/learnapidoc/workshop.html" TARGET="_blank" DATA-MSYS-CLICKTRACK="0" REL="nofollow noopener noreferrer">https://idratherbewriting.com/learnapidoc/workshop.html</A> to get a better sense of the material we'll cover and the agenda. This workshop is open to anyone but is intended usually for the following types of people:
<UL>
<LI>Professional technical writers looking to transition from GUI documentation into more API-focused documentation for developers.</LI>
<LI>Students learning how to prepare themselves technically to succeed in the tech comm field, which is becoming more focused on developer documentation.</LI>
<LI>Developers who are documenting their own APIs and want to know best practices for structure, terminology, and style with tech docs.</LI>
</UL>
As for the needed technical background for the course, you don’t need any programming background or other prerequisites, but it will help to know some basic HTML and JavaScript.
<H3>What You'll Need Prior to the Workshop</H3>
It helps to set up a few tools and other details prior to the workshop:
<UL>
<LI>Laptop with power cord. Make sure you bring your computer, as we'll be doing various activities. Power strips will be available to plug in. </LI>
<LI>Text editor. <A HREF="https://atom.io/" TARGET="_blank" DATA-MSYS-CLICKTRACK="0" REL="nofollow noopener noreferrer">Atom editor</A> or <A HREF="http://www.sublimetext.com/" TARGET="_blank" DATA-MSYS-CLICKTRACK="0" REL="nofollow noopener noreferrer">Sublime Text</A> are good options, and they work on both Mac and Windows.</LI>
<LI>Chrome browser. <A HREF="https://www.google.com/chrome/browser/desktop/index.html" TARGET="_blank" DATA-MSYS-CLICKTRACK="0" REL="nofollow noopener noreferrer">Chrome</A> provides a Javascript Console that works well for inspecting JSON, so we’ll be using Chrome. <A HREF="https://www.mozilla.org/en-US/firefox/" TARGET="_blank" DATA-MSYS-CLICKTRACK="0" REL="nofollow noopener noreferrer">Firefox</A> works well too if you prefer that. Also, in order to read JSON responses more easily in the browser, install the <A HREF="https://chrome.google.com/webstore/detail/json-formatter/bcjindcccaagfpapjjmafapmmgkkhgoa?hl=en" TARGET="_blank" DATA-MSYS-CLICKTRACK="0" REL="nofollow noopener noreferrer">JSON Formatter</A> Chrome extension.</LI>
<LI>Postman. <A HREF="http://www.getpostman.com/" TARGET="_blank" DATA-MSYS-CLICKTRACK="0" REL="nofollow noopener noreferrer">Postman</A> is an app that allows you to make requests and see responses through a GUI client.</LI>
<LI>curl. <A HREF="http://curl.haxx.se/" TARGET="_blank" DATA-MSYS-CLICKTRACK="0" REL="nofollow noopener noreferrer">curl</A> is essential for making requests to endpoints from the command line. Macs and Windows 10 computers already have curl installed. Windows users with older versions should follow the instructions for installing curl <A HREF="http://www.confusedbycode.com/curl/" TARGET="_blank" DATA-MSYS-CLICKTRACK="0" REL="nofollow noopener noreferrer">here</A>. (Note: Choose one of the “free” versions to install curl.)</LI>
<LI>Git. <A HREF="https://git-scm.com/" TARGET="_blank" DATA-MSYS-CLICKTRACK="0" REL="nofollow noopener noreferrer">Git</A> is a version control tool developers often use to collaborate on code. For Windows, see <A HREF="https://gitforwindows.org/" TARGET="_blank" DATA-MSYS-CLICKTRACK="0" REL="nofollow noopener noreferrer">https://gitforwindows.org/</A> to set up Git and the Git BASH terminal emulator. For Mac, see <A HREF="https://git-scm.com/download/mac" TARGET="_blank" DATA-MSYS-CLICKTRACK="0" REL="nofollow noopener noreferrer">Downloading Git</A>. </LI>
<LI>GitHub account. <A HREF="https://github.com/" TARGET="_blank" DATA-MSYS-CLICKTRACK="0" REL="nofollow noopener noreferrer">GitHub</A> will be used for various activities, sometimes to demonstrate the Git workflow and other times as an authentication service for developer tools. If you don’t already have a GitHub account, sign up for one.</LI>
<LI>Python. <A HREF="https://www.python.org/downloads/" TARGET="_blank" DATA-MSYS-CLICKTRACK="0" REL="nofollow noopener noreferrer">Python</A> will be used to create a local test server to run Swagger UI. Installation of Python is only needed on Windows (Macs have Python already.) On Windows, when you install Python, be sure to select the check box that says "Add Python 3.7 to PATH."</LI>
<LI>OpenWeatherMap API key. We’ll be using the <A HREF="https://openweathermap.org/" TARGET="_blank" DATA-MSYS-CLICKTRACK="0" REL="nofollow noopener noreferrer">OpenWeatherMap API</A> for some exercises. It takes a couple of hours for the OpenWeatherMap API key to become active, so it’s best if you get the API key ahead of time — then when you get to the OpenWeatherMap API activities, you’ll be all set. To get your (free) OpenWeatherMap API key, go to <A HREF="https://openweathermap.org/" TARGET="_blank" DATA-MSYS-CLICKTRACK="0" REL="nofollow noopener noreferrer">https://openweathermap.org/</A>. Click Sign Up in the top nav bar and create an account. After you sign up, sign in and find your default API key from the developer dashboard. It’s under the API Keys tab. Copy the key into a place you can easily find it.</LI>
</UL>
<H3>Workshop Location</H3>
The workshop will be held in Mountain View, California, at the <A HREF="https://www.computerhistory.org/" TARGET="_blank" DATA-MSYS-CLICKTRACK="0" REL="nofollow noopener noreferrer">Computer History Museum</A> in the Boole room, from 9am to 5pm. The address is 1401 N Shoreline Blvd., Mountain View, CA. Park in the normal museum parking area. Directions are available <A HREF="https://www.computerhistory.org/directions/" TARGET="_blank" DATA-MSYS-CLICKTRACK="0" REL="nofollow noopener noreferrer">here</A>. 
The Boole room holds 50 people. After entering the museum, go up the stairs to find this workshop room. As you're ascending the stairs, there's a clearly visible sign that says "Boole."  
In case you're new to the Bay area, traffic in the morning is congested, especially in the area near this museum. Plan to account for extra time as you move slowly on the freeway for a while. You can arrive as early as 8am, though the workshop will begin at 9am.
FAQs
How do I know if the workshop will be worthwhile?
I've given this workshop multiple times and have refined the material and activities to improve it after each one. You can see some feedback from previous workshops <A HREF="https://www.questionpro.com/a/showVOCDashboardII.do?mode=default&lcfpn=false" TARGET="_blank" DATA-MSYS-CLICKTRACK="0" REL="nofollow noopener noreferrer">here</A> and <A HREF="https://www.questionpro.com/t/PGCb2ZeGHW" TARGET="_blank" DATA-MSYS-CLICKTRACK="0" REL="nofollow noopener noreferrer">here</A>. On average from these last two workshops, about 57% of the participants rated it as Excellent and 40% rated it as Good.
What should I bring to the workshop?
Bring your laptop and make sure you've set up the tools and other setup specified in "What You'll Need Prior to the Workshop" above.
How can I contact the organizer with any questions?
Reach out to me, Tom Johnson, at tomjoht@gmail.com or online at <A HREF="https://idratherbewriting.com/learnapidoc/contact.html" TARGET="_blank" DATA-MSYS-CLICKTRACK="0" REL="nofollow noopener noreferrer">https://idratherbewriting.com/learnapidoc/contact.html</A> with any questions. 
What's the refund policy?
Refunds are possible 7 days prior to the workshop. After that, refunds are not possible. Refunds are charged a nonrefundable $25 <A HREF="https://www.eventbrite.com/support/articles/en_US/Troubleshooting/is-the-eventbrite-fee-refundable?lg=en_US" TARGET="_blank">Eventbrite processing fee</A>.
Is my registration fee or ticket transferrable?
Yes, you can transfer your registration/ticket to another person.
Is it ok if the name on my ticket or registration doesn't match the person who attends?
Yes, this is fine. When you arrive at the workshop, a list of registered names will be printed. Just write your name next to the person who officially registered so that I can account for everyone (and so I don't end up wondering what happend to so and so).
Will lunch be provided?
Yes, lunch will be provided at the event. Vegetarian options will be available, but only if you indicate so in the <A HREF="https://www.questionpro.com/a/TakeSurvey?tt=hfzamaUay3E%3D" TARGET="_blank" DATA-MSYS-CLICKTRACK="0" REL="nofollow noopener noreferrer">pre-workshop survey</A>. If you have a stricter diet (e.g., vegan or gluten-free), the provided lunch might not accommodate your diet. You can buy food in the museum's Cafe Bistro or at a nearby restaurant (e.g., Starbucks). 
Will breakfast be provided?
Yes, there will be pastries and coffee available in the morning, and some snacks (e.g., cookies, coffee) during the afternoon.
Are discounts available if I buy multiple workshop tickets, such as registering multiple people from the same company?
If you're purchasing multiple workshop registrations, you can receive for a 10% discount on the ticket price. Email me (tomjoht@gmail.com) for the promo code to enter during checkout.
Will this event be recorded?
I am not planning to record this workshop, though I might depending on attendee requests.
I need specific advice about a particular aspect of API documentation I'm working on. Will you provide some 1:1 consulting time?
Yes, usually we wrap up at around 4:30pm and then switch into 1:1 mode. At that time, I'll list all the names of people who want individual consulting, and we'll proceed through the list one by one. The venue closes doors at 6pm.
Where can I find the pre-workshop survey?
You can take the <A HREF="https://www.questionpro.com/a/TakeSurvey?tt=hfzamaUay3E%3D" TARGET="_blank" DATA-MSYS-CLICKTRACK="0" REL="nofollow noopener noreferrer">pre-workshop survey here</A>. This survey helps me understand the attendees a bit better so that I can prepare more efficiently.

Computer History Museum

Our {communityGuidelinesLink} describe the sort of content we prohibit on Eventbrite. If you suspect an event may be in violation, you can report it to us so we can investigate.

To report other categories of prohibited or illegal content, submit {link}

API Documentation Workshop

More events from Tom Johnson, I'd Rather Be Writing

Discover more events from Tom Johnson, I'd Rather Be Writing, from Science & Tech to other experiences you might love.

API Documentation Workshop

More events from Tom Johnson, I'd Rather Be Writing

Discover more events from Tom Johnson, I'd Rather Be Writing, from Science & Tech to other experiences you might love.

You might also like...

Browse more events with different dates, prices, and formats to find your next great experience.