I initially compiled this material to teach a series of workshops to a local tech writing firm in the San Francisco Bay area. They were convinced that they either needed to train their existing technical writers on how to document APIs, or they would have to let some of them go. I taught a series of three workshops delivered in the evenings, spread over several weeks.
These workshops were fast-paced and introduced the writers to a host of new tools, technologies, and workflows. Even for writers who had been working in the field 20 years, API documentation presented new challenges and concepts. The tech landscape is so vast, even for writers who had detailed knowledge of one technology, their tech background didn’t always carry over into API doc.
After the workshops, I put the material on my site, idratherbewriting.com, and opened it up to the world of technical writers. I did this for several reasons. First, I felt the tech writing community needed this information. There are very few books that dive into API documentation strategies for technical writers.
Second, I knew that through feedback, I could refine the information and make it stronger. Almost no content is finished on its first release. Instead, content needs to iterate over a period of time through user testing and feedback.
Finally, the content would help drive traffic to my site. How would people discover the material if they couldn’t find it online? If the material were only trapped in a print book or behind a firewall, it would be difficult to discover. But as content strategists know, documentation is a rich information asset that draws traffic to any site. It’s what people primarily search for online.
After having put the API doc on my site for some months, the feedback was positive. One writer said:
Tom, this course is great. I’m only part way through it, but it already helped me get a job by appearing fluent in APIs during an interview. Thanks for doing this. I can’t imagine how many volunteer hours you’ve put into helping the technical communication community here.
I love this course (I may have already posted that)—it’s the best resource I have come across, explained in terms I understand. I’ve used it as a basis for my style guide and my API documentation.
Hi Tom, I went through the whole course. Its highly valuable and I learned a bunch of things that I am already applying to real world documentation projects. … I think for sure the most valuable thing about your course is the clear step by step procedural stuff that gives the reader hands-on examples to follow (its so great to follow a course by an actual tech. writer!)
Other readers noted problems in obtaining API keys or getting the correct responses. As much as possible, I helped clarify and strengthen the content on those pages.
One question I faced in preparing the content is whether I should stick with text, or combine the text with video. While video can be helpful at times, it’s too cumbersome to update. Given the fast-paced, rapidly evolving nature of the technical content, videos go out of date quickly.
Additionally, videos force the user to go at the pace of the narrator. If your skill level matches the narrator, great. But in my experience, videos often go too slow or too fast. In contrast, text lets you more easily skim ahead when you already know the material, or slow down when you need more time to absorb the material.
One of my goals for the content is to keep this course a living, evolving document. As a digital publication, I’ll continue to add and edit and refine it as needed. I want this content to become a vital learning resource for all technical writers, both now and in the years to come as technologies evolve.
Get new posts delivered straight to your inbox.
© 2017, Tom Johnson