Over the last couple of months I’ve been presenting workshops on API technical writing in various locations. The workshops last a full day, and consist of lectures alternating with hands-on sessions. During the hands-on sessions, which last an hour, the participants work through learning material and exercises in a workbook. I put quite a bit of thought into the design of the workshop and workbooks. A few people have commented that the resulting structure works well, so I’ve decided to blog about it in the hope other technical writers will find it useful.
I’ve run the workshop three times to date: once in Mountain View, in collaboration with the Silicon Valley Chapter of the STC (Society for Technical Communication); once more in Mountain View, for Google technical writers; and once in Washington, DC, in collaboration with the STC Washington, DC – Baltimore Chapter.
First I’ll describe the workshop as a whole, then I’ll focus on the workbooks designed for participants to work through during the hands-on sessions.
Content of the workshop
The workshop is an introduction to API technical writing, designed for an audience of technical writers who’re new to APIs.
API stands for Application Programming Interface. Developers use APIs to make apps that communicate with other apps and software/hardware components. API technical writers create documentation and other content that helps developers hook their apps up to someone else’s API. For a technical writer, it’s an exciting, challenging and rewarding field.
The workshop includes the following parts, alternating between lectures and hands-on sessions:
- Hands-on: Play with a REST API.
- Lecture: The components of API documentation and other developer aids.
- Hands-on: Generate reference documentation using Javadoc.
- Lecture: Beyond Javadoc – other doc generation tools.
Design of the workbooks
When designing the content and structure of the workbooks, my aims were:
- Consolidate the learning points from the previous lecture, by guiding people to perform the same tasks that they’ve just seen demonstrated.
- Teach in-depth concepts and techniques that are better learned by active self-study than by watching someone else.
- Provide material for further study after the workshop is over.
- Cater for people with various skill levels in each subject area. Provide enough material for people who already know a bit about that particular subject, as well as for people just starting out.
- Prevent performance anxiety. Some people are quite nervous about taking part in workshops, worrying that they won’t be able to complete the exercises in the allotted time, and won’t be able to meet other people’s expectations or even their own expectations for what they’ll achieve during the workshop.
The first part of each workbook consolidates what participants have learned in earlier lectures. Subsequent parts of the workbook are more advanced.
As an example, here’s the introduction and table of contents for the first workbook:
Part 1 of this workbook consists of material covered in the previous lecture. Parts 2 to 4 contain new material.
Later sessions in the workshop build upon the material in parts 2 to 4 of this workbook, but without assuming that the participant has already had time to complete those parts.
Helping people feel comfortable
For hands-on sessions, I made it clear that people should feel free to pair up with someone. Some people work best alone, getting into the zone and focusing. Others work best with a partner. The partnering worked particularly well during the latest workshop in Washington, DC. A number of people paired up, and the room hummed with concentration.
I also let people know that the workbooks contain everything they need. In particular, all the code is available in the workshop material or via links in the workbooks.
I wanted people to enjoy the workshop, to feel they had time to get to know their fellow participants, to come away feeling that they’d learned something useful, and above all to have plenty of material and avenues for further investigation. Judging from the feedback, the design is working well. Thanks to everyone for your comments, and for the suggestions on how to improve the workshop for future incarnations!
What’s the difference between delete and remove? When should you use the word “delete” on a user interface or in a document, and when “remove”? Here’s an explanation that makes sense to me.
Use “delete” when you’re getting rid of the thing entirely – when it’s disappearing from the data store. Use “remove” when you’re subtracting it from a group or a list, but it remains available in the data store.
An example is the model of users and groups. Let’s say the user
arthurdent belongs to two groups:
earthlings. When Arthur no longer lives on planet Earth, you would remove
arthurdent from the
earthlings group. But if Arthur has departed the universe without leaving so much as a towel behind, you would delete the username
Here’s another example. Let’s say you have a number of credit card charges, which you’re adding to two expense reports. By mistake, you’ve added one of the charges to Expense Report 1 as well as Expense Report 2. So you need to remove that charge from the report. In addition, there’s an erroneous credit card charge of zero dollars, which you can delete without adding it to a report.
Works for me. :) What do you think?
On Wednesday February 11th, US EST (that’s Thursday here in Australia), I’m presenting a webinar about API technical writing. It’s the first in a series on API technical writing from the Society for Technical Communication. I’d love it if you could join me online.
The role of API technical writer is exciting, rewarding, and challenging. I’ve been working as a full-time API writer for 18 months now, and I love it!
APIs are a hot topic in our field, and technical writers with the skills to document them are in high demand. Many technical writers are keen to know more about the role, but it can be hard to find information. Sometimes there’s so much information that it’s difficult to know where to start. In presenting this webinar, my aim is to give you a good idea of the role of API technical writer, and some excellent starting points to explore the world of APIs.
Details of the webinar
Title: Introduction to API Technical Writing.
Date and time: Wednesday, 11 February 2015, at 2pm EST (GMT-5) – that’s 6am on Thursday here in Sydney!
Duration: One hour.
Fees and registration/signup: Please refer to the STC announcement: Part 1 in API Series: Introduction to API Technical Writing.
The session covers the following topics:
- What an API is and does.
- Introduction to the role of API technical writer and our audience.
- Overview of the types of developer products we may be asked to document – APIs and others.
- Examples of good API documentation.
- The components of API documentation, and the technical writer’s role in the creation of each component.
- A day in the life of an API technical writer.
- Tips on getting started in the role.
Here’s a link to the slides on SlideShare: API Technical Writing.
More in the STC’s webinar series on API technical writing
Following on from my introductory webinar, the next two sessions in the STC’s series have already been announced. In episode 2, Ed Marshall talks about documentating Java and C++ APIs. In episode 3, Joe Malin describes how to write effective code samples.
I hope to “see” you at the webinar!
To communicate with a REST API (or other web service API), you need to construct a request, send it over HTTP or HTTPS, then receive and parse the response. When creating an app, you do all that with code. But what if you just want to take a look around the API to see what it offers, before diving into the code? API explorers are your friend.
I’ve been putting together some information for a workshop on API technical writing. It’s been a rewarding exercise, because it’s made me think in a structured, educational way about what I do every day. A section of the workshop deals with various online API explorers that I’ve discovered over an extended period of time. This information is likely to be useful to many people, so I’m sharing it in a blog post.
API explorers offer a handy GUI alternative to a command-line tool like cURL. This blog post introduces the Advanced REST Client, which is a generic GUI for interacting with any REST API, and a few API explorers that interact with specific APIs.
Advanced REST Client
The Advanced REST Client is an add-on for Chrome browser. I find it very useful for sending a request to a REST API and receiving the response.
The Advanced REST Client offers a generic web form that you can use to craft an HTTP request, submit the request, and see the response. The screenshot below shows the Advanced REST Client in a Chrome tab. The top text box contains a request for the Flickr REST API. You can see the URL path and the URL parameters specifying the options needed for this particular request: the method (get public photos), the user ID of the person whose photos you want, and an API key.
(Click the image to see a larger version.)
Explorers for specific APIs
Developers of REST APIs and other web service APIs sometimes offer an API explorer, which people can use to take a look around the API before diving into the code.
The principle is the same as the Advanced REST client: an API explorer provides an online form where you can enter the parameters required for an API request, submit the request, and see the results.
The difference is that an API explorer is written for a specific API, whereas the Advanced REST Client is generic. The explorer therefore knows more about the API that it’s accessing. It can therefore:
- Present specific input boxes for the expected URL parameters and the input data expected in the request body.
- Hide such pesky complexities as user authentication. In many cases, you can sign in as a user of the web service, and the API explorer will create any authentication tokens that you need.
Flickr REST API Explorer
To see Flickr’s API explorer in action, you can experiment with requesting a user’s public photos from Flickr. Follow these steps to use the
flickr.people.getPublicPhotos method in the API explorer:
- Go to this link in your browser: https://www.flickr.com/services/api/explore/flickr.people.getPublicPhotos
You should see Flickr’s App Garden, showing a form with input fields for the arguments required in the request for public photos.
- Enter the following values:
- user_id: Paste in the Flickr user ID of the user whose public photos you wish to retrieve. A user ID is a string of characters with an @ sign in the middle. For example, use your own Flickr user ID or feel free to use mine: 31065906@N08.
- Leave all the optional arguments empty.
- Output: Select XML (REST). This is the default option.
- Authentication: Select Do not sign call. (Flickr does not require authentication for this particular API request.)
- Click Call Method.
- Scroll down to see the response. The API explorer returns the response body, and a copy of the request URL.
This screenshot shows the input fields for the
To find all the methods available in Flickr’s API explorer, go to this web page: https://www.flickr.com/services/api/
The methods are listed down the right-hand side of the page. For example, to find the method you’ve used earlier:
- Click the link on the words flickr.people.getPublicPhotos. You’ll see a documentation page about the getPublicPhotos method.
- Scroll to the bottom, and click the link to the API Explorer for the method.
Twitter REST API Explorer
Twitter’s REST API requires user authentication for every request. The API explorer is especially useful in this case, because it takes care of the authentication plumbing for you. All you need to do is give the explorer permission to access Twitter’s data via your Twitter username. Twitter uses the OAuth 1.0 protocol to authenticate the user. In this case, you’re the user, because you’re using the API explorer. This will all become clear if you follow the steps below. :)
- Go to the Twitter website and sign in as usual. (You do need a Twitter account to try this exercise.)
- Go to the Twitter API explorer at Exploring the Twitter API.
- Click the dropdown arrow under Authentication and select OAuth 1.
- A popup window appears, titled Request Twitter permissions. If you can’t see it, scroll down the page a bit.
- Click Sign in with Twitter.
- A window appears, titled Authorize Apigee’s API Console to use your account?
- Click Authorize app.
- You should see a short-lived message saying that you’ll be redirected back to the app. Then you’ll find yourself back in the Twitter API explorer. Under Authentication, you’ll see Twitter-<username> where <username> is your Twitter handle. For example, for me it shows “Twitter-sarahmaddox”.
- Under Select an API method, you’ll see a list of methods – these are the things you can do with the API. Click /statuses/user_timeline.json in the first set of methods (next to one of the blue “GET” buttons).
- A new set of panels appears. In the Query panel (the smallish panel near the top of the window), scroll down until you can see the user_id and screen_name fields. They’re right at the bottom of the panel, and not immediately visible. In the screenshot below, I’ve already scrolled down within the Query panel.
- Enter a Twitter username and screen name. In this screenshot, I’ve entered my own Twitter ID:
- Click Send. (The red button near top right.)
- A short-lived red-flashing message appears, letting you know the app is working. Then the response appears. If you see a green 200 OK, that means everything went well.
- Scroll down to see the full response. It’s in JSON format. The top part of it looks like this (but there’s much more):
Various Google APIs
The Google APIs Explorer provides a GUI interface for many of the Google APIs, including the Calendar API, the Gmail API, and many more:
Tech Comm on a Map now has a category for educational programs and courses, such as university technical communication degrees or certificates and other training courses. Take a look and let me know if you have something to add.
Tech Comm on a Map puts technical communication titbits onto an interactive map, together with the data and functionality provided by Google Maps. It’s a great way of seeing what we tech writers are up to, around the world. To find out more about the project, or to add something to the map, check out the project information page.