What I learned from organizing and running my first API documentation workshop from end to end

by Tom Johnson on Sep 8, 2019
categories: general

• What was different this time
• Financially worth the effort?
• Focus of the workshop
• Marketing and awareness
• Orchestrating activities for the workshop
• A more coherent narrative
• Catering
• Choosing a venue
• Workshop size
• Conclusion

What was different this time

Like I mentioned in my earlier announcement, although I’ve given more than a dozen API documentation workshops in the past, they were always organized through some other group, such as an STC conference or chapter, or were private workshops through companies, or other groups in which I was brought in to provide the instruction only. Just show up, teach the workshop, and leave. Nothing more.

It wasn’t until the workshop through Scott Abel in Menlo Park that I began to really think I should be holding and running these workshops from end-to-end myself. I started to wonder, why can’t I handle these other tasks too? How hard can it be to manage registrations through Eventbrite, or to order catering? And aren’t I already the perfect marketer with my blog?

I have a lot of scattered thoughts about these workshops, and I’m going to list them all in somewhat random order here.

Financially worth the effort?

First, are full-day workshops worth the effort financially? This is an important point that I’m hesitant to be transparent about, but it is a primary factor in evaluating these workshops. Giving a workshop takes a tremendous toll on me — both in the weeks preparing for them as well as the actual day itself. But they are financially worth it if you can attract the right audience. The most common audience for these workshops are company employees looking for continuing education opportunities, not necessarily new or unemployed technical writers trying to transition into the field, since this group often doesn’t have access to corporate budgets for training.

A few months ago I held a workshop organized through an STC chapter in North Carolina, and the thinking (mostly by the local leaders) was that the chapter members, not working at high-profile Silicon Valley tech companies, couldn’t afford to pay more than $75 for the full-day workshop. Flying all the way from California to North Carolina for the workshop and back for about 20 attendees didn’t amount to much profit (though I thoroughly enjoyed the day spent with them). In my post-workshop evaluation, a few attendees even indicated that the cost for the event was too low. Teaching workshops at the STC Summit had double the profit but was even more draining because it involved also giving multiple presentations during the conference itself.

For the workshop I organized in Mountain View last week, I charged either $399 or $499 (depending on the registration time) and had 28 attendees. The net profit was much more than that of the Raleigh event. So financially, it really felt worthwhile.

Although I’d like to ignore the financial costs of such an event in its evaluation, I must be a realist. I have four kids ranging between ages 9 to 18, with the first one heading off to college at UCSB in the fall. Starting this year, we’ll be paying tuition for our children every year for the next 14 years. As soon as one kid finishes college, another will be just starting out.

Even public colleges in California cost about as much as a Model 3 Tesla each year. Basically, college costs 3x the amount it was when most of us went to college. (For a good read on this and how it affects families and society, see How Paying for College Is Changing Middle-Class Life.) My wife is also in a masters program. Based on the need to pay tuition, I felt like I need a more marketable side-gig to really make it in the Bay area (even with a good company salary).

In deciding to teach the workshop, I also had to reduce my commitments elsewhere. I received an invitation to teach an API doc course at a UC extension school, which would basically run 2 months, require about 5 hours a week, and net $2,500. That kind of endeavor sounds enriching and worthwhile, for sure. But those activities would drain all the free time I have and would make organizing an event like a full-day workshop more challenging.

To find attendees able to pay several hundred dollars for a full-day workshop, I’ve found that you have to attract currently employed technical writers who work for companies willing to invest in the continuing education of their employees. At most companies I’ve worked at, providing educational opportunities for employees to further their skills and knowledge is fairly common. But this also means that the workshop must take place on company time, such as a day during the week. You can’t really hold a workshop on a weekend and attract the same audience, as this digs into the employees’ personal time.

As I’ve analyzed the traffic on my blog over the past decade, I’ve seen that traffic always dips during the weekends and jumps back up during the weekdays. Technical writing is basically a workday task, not anyone’s weekend hobby (though there are some enthusiasts who are exceptions). In summary, the workshop should basically be an extension of work.

Focus of the workshop

Another important point is to focus on a subject that addresses a current pain point people have. There is almost no other topic in the tech comm industry as compelling as API documentation. If I were to hold a workshop on another topic, such as my simplifying complexity series, I doubt many people would sign up. API documentation has been and continues to be a topic of continual interest at tech comm events as well as a huge source of traffic to my website. When people donate to my site, they invariably donate because of the API documentation course rather than the blog.

Why is API documentation so popular? In part, API documentation draws people because it is a challenging specialization of tech comm. Learning to write for developers requires you to learn new skills, write for new user behaviors, survive in a new technology landscape, navigate new publishing tools, figure out developer workflows, collaborate in source control, and more. I even feel a bit overwhelmed in this space by the pace and intensity of it all. There is no other topic in our industry that commands so much attention and puts so much pressure on technical writers as API documentation — in all varieties, whether working with REST or native libraries.

During the workshop, one technical writer who has 30+ years of experience writing developer documentation said that she still lacks confidence on many developer documentation projects. That was why she was taking the workshop — to build her confidence, despite her 30+ years of experience in the field (much of it right here in Silicon Valley)! That kind of blew my mind.

Marketing and awareness

To stay up-to-speed in the API documentation space, I dedicate a lot of time and thought development to API doc topics. Although I might want to write about topics outside of API doc on my blog, those topics tend to perform poorly (get low traffic) and not result in much over time (they go out-of-date). It’s a better investment to expand on some topic in my course, as it attracts more viewers and readers who already have an affinity in that space.

A while ago I wrote a post called Why I decided not to become a grasshopper expert, or, Not deciding your focus based on where readers are clicking, in which I argued that just because 75% of your site’s traffic is focused on X, it doesn’t mean you should write about X on your site. This topic no doubt gets into deep philosophical questions about the purpose of life, but there are realities at play here that are hard to ignore. If you want to thrive in the API doc space, it requires a lot of time — time spent consuming, reading, exploring, installing, playing, experimenting, etc., with topics, tools, and themes related to APIs. Try to carry about some other endeavor, such as writing a novel or pursuing a side hobby (e.g., restoring an old car), and you will find your time dissolves like sand.

I have also realized that blogging/writing about API documentation makes me a natural marketer for the topic. Bloggers are consummate marketers for the topics they write about, and every time I write a post that touches upon API documentation topics, the content brings readers to my site and builds trust. Many people who take the workshop have been reading my site for a number of months or even years. Each post (hopefully) builds up a reputation of trust and confidence for potential workshop attendees.

Orchestrating activities for the workshop

One detail that is quite difficult for me is figuring out hands-on activities for the workshop. It’s one thing to write posts and articles addressing various API documentation topics (and I love the reflective mindset), but it’s another to structure that learning into some kind of engaging, hands-on activity during a full-day course. What activities do you do, especially for abstract concepts?

For some aspects of API documentation, there are clear sorts of activities — making a call in Postman or curl, or rendering a Swagger UI display from an OpenAPI specification file. Exposure to these tools is what makes the API documentation course come to life, and when attendees learn how to use a new tool for some documentation end, light bulbs go on.

But much of the work of documentation involves working with abstract, conceptual topics, and it’s hard to make hands-on activities for these topics. For example, take this new section I added on documenting code. How exactly do you move from the conceptual into a hands-on activity (that can be accomplished in 10 minutes) with documenting code?

And yet, if you simply lecture for an hour on the topic, you’ll soon tire attendees as well as yourself. Try lecturing for 8 hours straight and see who is still alive at the end of the day.

My activity for documenting code involved having attendees look at various documentation tutorials and try to classify the approach. It worked okay, but in retrospect I needed more direct links to actual tutorials rather than asking attendees to find a tutorial in an API doc site they were interested in.

I often hear feedback from attendees about how illuminating it simply is to examine and compare various API documentation sites — I think for many, it’s the first time they foray outside their company’s API walls, and it’s often eye-opening. Even so, looking at other doc sites isn’t a super engaging activity. I think for the next workshop, I might have attendees try to complete an actual getting started tutorial from a site.

A more coherent narrative

After the workshop, one person said he was having trouble connecting all the dots. I touched on a lot of different topics during the day, but he wanted more of a sense of how it all fit together. Unless I am misinterpreting him, it seemed like he wanted a more straightforward process, like a 1-2-3 approach to writing API docs. Maybe in a course on DITA or Information Architecture, there is a clear approach, maybe even a methodology that can be trademarked or copyrighted, where you follow a specific pattern for something to achieve a result.

His comment got me thinking quite a bit, especially in the context of other feedback. What I’m realizing is that people would prefer more clearcut techniques and strategies that they can implement. This leads me to a larger observation. In the academia and with writing in general, there’s a tendency to show how topics that seem simple on the surface are actually complex underneath. The opposite is also true — that which seems complex on the surface might have simple patterns driving it underneath (like a fractal). At any rate, while some spaces might prefer the former approach (revealing complexity), most corporate training prefers the latter (simplifying complexity). This is because people are already persuaded by the complexity of the topic — that’s why they took the workshop.

Would it be possible to create a 1-2-3 approach to writing API docs? In reality, this is what we do as technical writers most of the day. Even if there are many paths users might take, or even if the implementation could be done in a different order, or even if there isn’t any sequential order inherent at all in the task, I create workflows that articulate a step-by-step path (1-2-3) to creating or configuring the product. (I wrote about this in my post Principle 1: Let users switch between macro and micro views.)

Perhaps I should apply the same (fictional) sequential approach with API documentation. With this approach, I might restructure my course into a wizard of steps that describes how to do API documentation. Something like this:

1. Ramp up on the technology by devoting 60 minutes to learning the project’s tech in the morning.
2. Start testing the product and making requests on your own.
3. Document the reference topics, since they constitute the core of your product’s functionality.
4. Structure the reference content into an OpenAPI specification document.
5. Build out your reference output using one of these 5 tools…
6. Develop conceptual content for these 6 topics: Overview, Getting Started, Authorization, Rate Limiting, Status and Error Codes, and Quick Reference.
7. Create a Getting Started tutorial describing an end-to-end task.
8. Create code tutorials for the most common tasks for your API.
9. Publish your docs using docs-as-code workflows and tools.
10. Some other task here because we can’t just end on an uneven number like 9.

And so on. Maybe I call this “Tom’s 10-step approach to API documentation,” or the “Ten Habits of Highly Effective API Documentation” or something (kill me now to avoid another cliche). Having a specific approach, even if no project would ever fully implement it in this exact order, or even if no project would require each step, might give people a clear structure and direction that they need. Then they could adapt and modify it as needed depending on their project, but at least they would have some specific methodology and direction.

Perhaps this approach merely reflects the sort of thinking of a technical writer, of someone whose job it is to draw clear lines through murky, confusing products. Much of tech docs is a kind of fiction, of creating and defining a process to achieve an end even if that process is arbitrary and debatable, and even if there are so many other ways to approach something. You need to give users some steps to follow, so they have a starting point and direction. (This is really how tech comm and literary fiction intersect: we’re both in the process of creating narratives through random plot points.)

Even if the reality is much more abstract and fuzzy, more nuanced and complex, the clear path and approach gives users a methodology that might be what’s necessary to feel like all dots are connected. It’s kind of like Scrum — sure, the approach doesn’t always work and nearly everyone modifies and adapts it for their current situation, and also complains about it, but at least it gives users a methodology.

Catering

Now back to some more mundane details. I learned that arranging catering is actually pretty easy. I used Specialty’s, which turns out to be about as hard as ordering a Lyft. You just log into the site, select the food you want and the times you want it delivered, and someone shows up with food that they set up on a table.

Having never ordered catering before, I stressed quite a bit about catering, imagining that attendees might complain that the food (boxed sandwich lunches) were poor or that there weren’t enough vegetarian options or something. Instead, I just ordered 1/3 vegetarian sandwiches, and it worked out well. I also ordered breakfast and an afternoon snack.

Overall, catering didn’t cost more than $1,000, and it worked great. Then again, I’m not a “foodie,” so maybe people were just polite, but I’ve never read any workshop review in which people rated the workshop poorly due to the food. As long as there is an abundance of food and coffee, people are generally satisfied.

I also didn’t need to have a second helper to meet the caterer or arrange the dropped-off food on a banquet table. In the afternoon, the delivery person simply left the food in bags, and this took me about three minutes to set up. But for the other two food dropoffs, the delivery person arranged the food on the table. I was relieved to see that I could still teach the workshop while managing the catering, which reinforced my plan to orchestrate the whole workshop myself.

Choosing a venue

The venue at the Computer History Museum in Mountain View worked out well too. I chose the Computer History Museum because my kids have had various tech workshops there in the past, and I was familiar with the space. It was easy to connect to the wifi, the location was central, and the room was just the right size for about 30 people (even though it actually holds 50). Additionally, the event coordinator was helpful and available. The Boole room was also easy to find (just up the stairs), and it was relatively inexpensive — just $1,100 for the day, including AV equipment.

The place even had a cafe in case people wanted to get their own food. The only drawback was that admission to the museum itself would have cost extra, though there wasn’t really much time for attendees to wander off on their own anyway.

Would I choose the Computer History Museum again? Sure, but here’s what I realized. People who attended the workshop were mostly South Bay locals. There were some people coming from farther away, one even from outside of California, but by and large, you have to choose a venue near the workplace of the audience you’re trying to attract.

I know this sounds somewhat obvious, but this also means that for future workshops, I’ll likely need to travel about to other urban areas to attract attendees from companies in those areas. I sort of had in my mind that people would come to me instead of me coming to them. Silicon Valley is, after all, a tech hub, and with past workshops, a few people flew in from San Diego. In Raleigh, one attendee even drove up from Atlanta. But by and large, people who are taking a day off of work for the event don’t want to drive too much farther than why would normally travel for work.

Given the number of tech writers in the Bay area (4,000+, I think), I could likely repeat the Mountain View location again with success, but I am also thinking of holding the workshop in other urban centers — downtown San Francisco, San Diego, Seattle, Austin, Boston, Atlanta, and so on. The problem is that I’d need to locate a venue in areas that I’m unfamiliar with, and trust that the venue has everything I need prior to the workshop. I’d be reliant on the AV equipment (unless I buy my own projector) and other details, almost like buying a house via “site unseen.”

Fortunately, in looking at other urban places, I’ve come to discover that there are many websites that facilitate exactly this sort of venue-scheduling task. For example, Peerspace lets you select the venue you’re looking for based on various filters (location, size, cost, AV equipment, and more). You can read reviews of the space and more. Overall, I’m coming to realize that technology has dramatically simplified event management.

Workshop size

Exactly how many people can attend a workshop? When I created the workshop on Eventbrite (which, by the way, makes managing the event registration and payment extremely easy), I put the limit as 50, even though most workshops I’ve seen from others limit workshop sizes to around 20 or so. I was fortunate that only 28 signed up, because I think any size over 30 would have been unmanageable.

To scale to larger sizes, I had a plan. I would refine my activities to include clear step-by-step instructions (I was, after all, a technical writer, right?). And I would also print out the activities into booklets that I passed out. For every previous workshop I’d given, I simply required attendees to follow instructions on a web page. But toggling between screens on a laptop is cumbersome, so I decided to print booklets this time.

I spent quite a bit of time fine tuning the web activity booklet into a PDF booklet. After some tweaking of CSS, I generated a PDF directly from the website content — it looked decent. Then I waited until the night before to print out 28 booklets (each booklet contained 20 double-sided pages).

Even with my Brother HL2360D Laser printer (which performed like a champ), this herculean task took about 3 hours. My kids were in awe to see the printer printing out page after page non-stop for so long, and I even made a late-night trip to Target to get more paper. Miraculously, I had just enough toner from a “high-yield cartridge” to print everything. 40 pages x 28 booklets is 1,120 pages. Apparently, printing this at a nearby print shop that charged 8 cents a page would have cost hundreds of dollars. But doing this print job the night before was not smart, as it stressed me out a lot. I thought my toner cartridge would run out halfway through and that I’d have to finish the job at Kinko’s (luckily it didn’t).

Unfortunately, as much as I tried to make my instructions flawless regardless of the platform (Windows versus Mac), attendees ran into issues. And one issue was kind of disastrous. To get the Swagger UI project to render an OpenAPI spec locally, you have to run a web server on your computer. The easiest way to do this is to install Python and run a SimpleHTTPServer. So I created instructions for doing this, but I underestimated the complexity of this task across platforms and versions.

First, some Windows PC people who installed Python were never prompted to add Python to their PATH. This means python wouldn’t be recognized in the command prompt. Others had issues as well, which prompted me to try simplifying this task on the fly by having people use a web-hosted URL to an OpenAPI spec instead (then they wouldn’t need to run the Python SimpleHTTPServer). But communicating these instructions was challenging because I was modifying the printed instructions that everyone already had.

All attendees really had to do for this activity was download a ZIP package from GitHub, unzip it, open the index.html file in a text editor like Sublime, customize the reference to the OpenAPI spec file with another file, then open the index file in the browser to view the result — it seemed easy enough, but getting 28 people to successfully do this is surprisingly hard.

I need to simplify this activity even more and give attendees more time to complete it. I read quite a few post-workshop survey comments about needing more time to do the activities, so this is something I need to work on in the future. I should also not try to modify these activities on the fly like I did. In retrospect, I am constantly realizing that I need to simplify the activities and give users more time to complete them.

Additionally, watching people struggle with steps that I think are pretty straightforward made me realize a few things. First, tech writing is hard. Writing good instructions that people of all backgrounds and computer setups can follow flawlessly is extremely difficult. I might think my instructions are flawless, but when I add in the variety of operating systems (and admin rights on those systems), and other assumptions, I see how many issues crop up. Some users even had security restrictions on their laptops that prevented them from making any web calls at all.

It can take a long time to great instructions. I can only imagine how much more challenging the docs I write at work (which describe much more complicated tasks for developers) must be to follow. Fortunately, I guess I don’t have to bear watching people try to follow them in real-time during a workshop.

My second realization is that I might be more technical than I think. Or I might just be more familiar with these specific technical tasks. I don’t know. I have become numb to some assumptions or other details that otherwise jump out at other people. It is actually quite difficult to know how technical you are or aren’t. Everything is relative, and there are so many nooks and crannies of different technologies, it’s impossible to really tell. But overall, my sense is that perhaps some of these activities seem easy because I’m more technical than I give myself credit for. Unfortunately, this isn’t necessarily advantageous when writing docs.

Overall, my plan to handle the larger workshop size through printed instructions didn’t work so well, though everyone unanimously liked the printed booklets. I’m confident that by simplifying the activities in places, I can overcome the issues described here.

I also did a couple of other things to reduce the technical issues during the activities. I made sure attendees had everything installed prior to the workshop, and I arrived an hour early to help out anyone who needed assistance. I also brought in some red cups that attendees could put on their desks when they got stuck. The red cups worked okay, and most people installed everything prior to the workshop. But there is still much to be done in this area for improvement. I don’t know why I’m not better at the activities part (I’m even a former writing instructor).

After the workshop, it was around 5:30pm, and I had been up for 12 hours. I ordered a Lyft for a ride home, and I got a driver who drove his car like a racecar, accelerating and decelerating quickly in congested traffic. Exhaustion turned to nausea, and when I finally reached home (thankful that I didn’t throw up), I migrated into escape mode, watching three episodes of Derry Girls with my family and then some episodes of MindHunter on my own, until every neuron in my brain ceased its activity and I simply closed my eyes to sleep.

Conclusion

Now that a week has passed since the workshop, I’m eager to hold another one. In fact, I’m planning to hold maybe 5-6 more workshops this coming year, located in different tech hubs. I think I can improve my material with each one and get a better workshop and approach. If you have any input or insight for me to enhance this experience, feel free to share it with me.

I scheduled my next API documentation workshop for November 19, 2019, in the Financial District of San Francisco. The venue, which I found through Peerspace, looks ideal. I set the capacity for 25. If you’re interested, consider spending a day with me in the workshop. The workshops get better each time.

About Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.