Designing a workshop and workbooks

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:

  • Lecture: Introduction to APIs, including a demo of some REST and JavaScript APIs.
  • Hands-on: Play with a REST API.
  • Lecture: JavaScript essentials.
  • Hands-on: Play with a JavaScript 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.
  • Take the varying interests of the group into account. Some participants are more interested in REST APIs, for example, whereas others want to focus on JavaScript or Java. People can start each workbook during the allotted session, but then decide to focus only on a particular workbook for further study.
  • 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:

Workbook table of contents

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.

Introducing a hands-on session

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!

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 4 April 2015, in technical writing and tagged , , , . Bookmark the permalink. 4 Comments.

  1. I would love to attend a workshop like this – API is kind of an intimidating topic and this would be so helpful! Nice job🙂

  2. I was signed up for the Washington, DC workshop but came down with the flu the day before and missed it. Is there any way to get the workshop materials? Thank you!

    • Hallo Meg

      So sorry you missed the workshop! The workbooks aren’t (yet) available online, because their format is designed for the interactive nature of a workshop. I also need to figure out a plan for ongoing support, and for content licensing. I do plan to make all the material (lectures/slides as well as workbooks) publicly available as soon as I have the time to take care of the format etc. Please stay tuned to this blog for updates.

      Cheers
      Sarah

  3. Is there anything planned in the Bay area anytime sooner? This seems like an awesome workshop!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: