Why I developed this course
I initially compiled this material to teach a series of workshops to a local tech writing firm in the San Francisco Bay area. They felt they either needed to train their existing technical writers on how to document APIs, or they would need 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 REST API documentation.
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 information would be useful to the tech writing community. 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 hits the mark on its first release. Instead, content needs to iterate a while through user testing and feedback. Just as this iterative review helps refine user documentation, the same principle applies to course material as well. I’ve given dozens of presentations and workshops on API documentation for several years now, and each time I’ve used the feedback to improve this content.
Finally, the content would help drive traffic to my site. In fact, visits to the API documentation course pages outperform visits to my blog. I reflected on this traffic source in a blog post — see If writing is no longer a marketable skill, what is? 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!)
And another:
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 and multi-week course. 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.
And another:
I am nearly in tears after finding this site! I think I stumbled upon it some time ago, but I must not have been ready for what you have to say. NOW I am ready! As a former technical writer now knowledge manager, I stumbled upon API writing and have learned a lot simply by being curious and observant…
Of course, not all comments or emails are praiseworthy. Some people note problems on pages, such as broken links or broken code, unclear areas or missing information. As much as possible, after receiving this feedback, I go back and clarify or strengthen those areas.
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 get 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 skip ahead when you already know the material, or slow down when you need more time to absorb concepts.
Despite the constant changes in the technology landscape, I want to keep this course current and up to date. As such, 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. If you have general feedback about this course, feel free to drop me a line.
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.
2/166 pages complete. Only 164 more pages to go.