Reflecting on my latest SF API doc workshop
Picking the date
First, I made a rookie mistake by choosing a date that coincided with Dreamforce, which is Salesforce’s big conference event. This event brought in 171,000 people into the city this year, which made it difficult for some of my workshop participants to book hotels. (One group in Portland didn’t come to the workshop because they couldn’t book a hotel.)
Additionally, the city was extremely crowded. After the workshop, I was walking back to Caltrain, and it felt like I was walking through parade-like streets. It didn’t help that my venue was pretty close to Dreamforce’s headquarters.
Even so, we had 19 people attend the workshop. This is fewer than the 28 who attended the Mountain View workshop. But I wanted to limit the attendance to 25 or fewer anyway, so I was happy with 19. In fact, getting 19 people to attend a workshop during Dreamforce is kind of a miracle, as well as reserving a classroom in the area. Anyway, next time I am triple-checking to see if what conflicting events are in the area. I had other tech comm events on my mind, but not non-tech-comm events.
Many people who attend these workshops either work several blocks away from the venue, or they come from out of state. We had people who flew in from Minnesota, Texas, New York, and Washington. The diversity of locations is sometimes stark — either a few blocks or states away. Some also drove in from about an hour away, so I guess we get a solid mix of locations.
The main feedback I received from the previous Mountain View workshop was around the activities — I didn’t give attendees enough time to complete them. (If you think creating API activities is easy, check out this post from API Handyman: Lessons learned while demoing API to non-developers — it made me feel much better about the technical issues I’ve encountered with even the simplest of activities.) This time around, I isolated the more difficult activities and made them optional. This would allow more advanced attendees to have something to do while not making the other attendees feel like they were leaving some activities incomplete. This time, no one really complained about the activities, so I think this new approach fixed the issue.
However, the overall workshop score was about the same. I’ve been giving this same workshop survey each time, and here’s how the ratings compare:
- In the San Francisco workshop, 39% said the workshop was excellent, 56% said it was good, and about 5% rated it as average. See San Francisco survey results.
- In the Mountain View workshop, 45% rated it as excellent, 45% rated it as a good, and 9% as average. Mountain View survey results.
- In the Denver STC19 workshop, 58% rated it as excellent, 38% as good, and 4% as average. Denver - STC19 survey results.
- In the Raleigh STC/WTD event workshop, 56% rated it as excellent, and 44% rated it as good. Raleigh survey results.
- In the Menlo Park workshop, 26% rated it as excellent, 63% rated it as good, and 11% as average. Menlo Park survey results.
So on average, about 45% of participants rate the workshop as excellent and about 49% rate it as good. Overall, I keep asking myself, what would it take to move up significantly in the overall workshop rating to an 80-90% excellent rating? If the problem wasn’t simply the activities, what then?
My wife says that maybe tech writers are just tough critics and are reluctant to give an excellent rating unless it’s absolutely phenomenal. And C’mon, she said, the topic is API documentation. How exciting can this be?
I can’t help but also think that leveling up would require me to become a better presenter. Perhaps I need to become more charismatic, energetic, articulate, and personable? Honestly, I don’t know if I have that in me. I have never considered myself a “presenter,” even though I’ve given more than 100 presentations over the past decade. In my presentations, my only real strategy is to try to shape my information around a general story, but it’s harder to do that over the span of a full-day workshop.
A few days before the workshop, I was updating slides and other information and was generally stressed (some work projects unfortunately coincided as well). I told my wife I was in the “pit of dread” but would be fine afterward the workshop.
Meanwhile, she was also busy working on an upcoming presentation for her class (she’s in a masters program at Stanford), and she was enthralled by some new detail she had learned that would relay in her presentation. She was bubbling with excitement to show me the timeline she’d created, and would frequently erupt into long monologues about some epiphany she had realized through her research.
It dawned on me that she wasn’t in the “pit of dread,” as I was. She was on the “edge of excitement” or something. (Sorry for the cliches; I’m trying to capture the different states.) She did say she was nervous and anxious about her presentation, but you could also see that she was fully floored by the topic and was looking forward to her 15 minutes of presentation time, even if she was nervous.
I realized that if I want to stick in this workshop game long-term, I’ll need to get out from the “pit of dread” mentality and shift over to the edge of excitement. The only way to do that is to immerse myself in continual learning. If you give the same presentation over and over again (like I did with my Trends presentation last year), it eventually gets stale. Some people might like repetition, but I can’t even stand to watch the same movie twice. What engages me more than anything is learning.
In order to stay on the edge of excitement for the API workshop content, I need to be even more immersed in API doc learning, constantly adding new material to the course, enriching it with new insights, technologies, examples, research, and other information in a constant way. It can’t be a static topic.
Fortunately, API documentation is a subject that is in constant flux. If you take a screenshot of an API doc site today, in one year that page will either be a 404 or will have a totally different design. I’m not kidding. Additionally, on a technology level, REST APIs are now competing with gRPC APIs, GraphQL APIs, and more. Doc publishing tools involve “headless CMSs” and other platforms. There is constant evolution.
Despite the challenges, this fast pace of technology development is exactly what fuels interest in the course. If API docs were a topic like XSLT stylesheets or something, there wouldn’t be material for a full-day course in a perpetual kind of way. (Actually, someone told me that there’s a guy who transitioned to giving workshops around the country on XSLT and XSL-FO for the remainder of his career until he retired, so maybe that topic works too.)
It’s my hunch that if I can dive deeper into API learning, I might be able to infuse my course with more of an “edge of excitement” attitude that would help me level up. I’m already half way through The Design of Web APIs by Arnaud Lauret, and am planning a podcast interview with him next week.
I should probably also look to read books on workshops and presentations. After viewing some of my workshop videos, someone recommended that I read Carpe Audience: Give Better Presentations Despite PowerPoint by John-Michael Keys, and I plan to do that. So far in his book, he says not to read bulleted lists, which is something I don’t believe I do (at least not frequently).
I do like experimenting in small ways with each workshop. In the Mountain View workshop, I introduced a new section called “Documenting Code.” In the SF workshop, I evolved that section to “Code tutorials.” I’m fascinated by how scarce code tutorials are on doc sites, and how even on big-name API doc sites like Stripe, the tutorials seem a bit wordy. For my next workshop, I’m planning to go deeper with this tutorials section and also include a discussion about usability and other topics.
I might also try experimenting in more radical ways. My target audience is technical writers working for companies who are transitioning into more API doc responsibilities. Perhaps I should ask tech writers to share what they’re working on, so that we can dissect and analyze it more directly in the course. Some attendees often explain the challenges they’re facing, and by weaving some of these specific challenges directly into the course, it could bring more of the material to life in a real way. Then again, unless the content resonates with your own challenges, it might feel like listening to someone else’s question.
I am going to keep giving these API documentation workshops. Not only does it keep me rooted in an interesting space, it gives me more focus and structure to my online writing. When you can write about anything and everything on your blog, this 360-degree flexibility actually reduces the number topics that spring to mind. In contrast, limiting your scope generates more ideas to write about. It’s a paradox.
Additionally, the workshops also provide a financial incentive that drives content generation on my site. The reality of most web content efforts (e.g., blogs, e-magazines, or other sites) is that if they don’t make enough side money to be worthwhile, they eventually get de-prioritized. This is why tech comm blogs are so far and few today. I had some advertising on my blog early on, and this helped incentivize me to keep posting even when my interest lagged. Anyway, I’m just saying that adding a financial element to content development isn’t a bad thing and helps keep the content wheels turning.
I am already planning my next workshop. The next API documentation workshop will be in Los Angeles on January 23, 2020. I checked conflicting events, and the only conflict I see is that Jan 23 is the same night Jason Mraz is giving a concert. Since I’ve never heard of Jason Mraz, I think I’m safe. You can check the API doc workshop out on EventBrite here.
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.