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 their writers 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 tech comm field for 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 broader 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 or courses that dive into API documentation strategies for technical writers.
Second, I knew that through feedback, I could refine the information and make it better. Almost no content is finished on its first release. Instead, content needs to iterate over a period of time through user testing and feedback. This is the case with help content, and it’s the same for course material as well.
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. Content is a rich information asset that draws traffic to any site. It’s what people primarily search for online.
After putting the API doc on my site for some months, the feedback was positive. One person 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.
Another person commented:
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!)
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….
These comments inspired me to continue adding to the course, building out more tutorials, sections, and refinements. What began as a simple three-session course transformed into a larger endeavor, and I aspired to convert the content into a full-fledged book. I continue to receive emails from technical writers, many of whom are trying to transition into developer documentation. The other week someone wrote to me:
Just an email to thank you for the wonderful API course on your site. I am a long-time tech writer for online help that was recently assigned a task to document a public API. I had no experience in the subject, but had to complete a plan within a single sprint. Luckily I remembered from your blog posts over the years that you had posted material about this.
Your course on YouTube gave me enough information and understanding to be able to speak intelligently on the subject with developers in a short timeframe, and to dive into tools and publishing solutions.
Of course, not all comments or emails are praiseworthy. A lot of people note problems on pages, from broken links to broken code, unclear areas or missing information. As much as possible, through this feedback I helped clarify and strengthen the overall content.
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, that’s 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