Search results

Why I developed this course

Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 4,500+ subscribers

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 REST API documentation.

After the workshops, I put the material on my site,, 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. I’ve been giving both presentations and workshops on this content for several years now.

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!)

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 more:

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 skim ahead when you already know the material, or slow down when you need more time to absorb concepts.

One of my goals for the content is to keep this course a living, evolving document. 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. My hope is that it will primarily serve the following audiences:

  • Professional technical writers looking to transition from GUI documentation into more API-focused documentation for developers.
  • Students learning how to prepare themselves technically to succeed in the tech comm field, which is becoming more focused on developer documentation.
  • Developers who are documenting their own APIs and want to know best practices for structure, terminology, and style with tech docs.

If you have general feedback about this course, feel free to drop me a line.

7% Complete

7/110 pages complete. Only 103 more pages to go...


Want to buy me lunch? Click the Donate button below to donate $10 through Paypal.