I’m a big fan of the blog I’d Rather Be Writing. Written by Tom Johnson from San Jose, the blog is an invaluable resource for technical writers as well as an inspiration for blog writers. Not only does the author explore technical writing trends, he also gives away an entire course worth of information on sought-after training topics.

If you haven’t encountered Tom’s blog yet, do yourself a favor and head on over. There’s too much content on the site to cover exhaustively (he has been blogging regularly for over a decade), but here’s a short tour of a few major attractions.

Beginners

Because Tom gets asked questions by individuals who want to work as technical writers, he has written dozens of articles with advice on preparing one’s portfolio and getting acquainted with the field’s many expensive documentation creation tools. On the Beginners tab of the main menu, there’s a page with 80 items tagged as relevant to technical communication newbies.

Much of the content in this section is self-explanatory. For example, there are articles entitled “The problem with Frequently Asked Questions (FAQs) in documentation” and “The variety of tools tech comm professionals use”, all about imparting knowledge to people early in their careers or refreshing the memory of seasoned professionals.

The Academic/Practitioner Conversations Project

I’ll let Tom tell you about this project in his own words…

I’m engaged in a year-long experiment to see if we can change attitudes in the industry that practitioners have toward academics in the same field, and vice versa. The project is called Academic/Practitioner Conversations. By breaking down the barriers that separate the two groups, I hope to encourage more interaction and knowledge sharing between tech comm academics and practitioners….

Tom Johnson

Tom uncovered interesting findings in his survey of practitioners and academics. The former aren’t sure that academics really understand the issues they face, and the latter said that they weren’t writing for practitioners as their main audience.

In Tom’s opinion, the differences between these two groups creates a problem of relevancy because each group tends to talk past the other. Acknowledging this problem is a necessary step before “breaking down content barriers” and getting the two groups to cooperate.

Documenting APIs

The API Documentation course tab actually opens a wormhole to a site-within-a-site. Be prepared to find yourself in the API documentation zone, a dimension nearly as vast as space and as timeless as infinity. I mean to say, it’s hefty.

This is the Internet’s premiere primer for helping technical writers to learn the best practices of writing documentation for a software developer audience. Although there are many different types of developer-facing technical documents, Johnson focuses primarily on RESTful API documentation and secondarily on native library APIs.

The course is accompanied by video presentations with hands-on exercises so you can not only learn by reading but learn by doing. These are some of the main areas of the course:

• Documenting API endpoints
• OpenAPI spec and Swagger
• Publishing API docs
• Getting a job in API doc
• API glossary and resources

One of the most interesting portions of the course is to learn about the context in which REST APIs exploded in popularity to eventually become the building block of interconnectivity on the World Wide Web, and how these APIs have peculiar features when it comes to documentation requirements.

Tom advises that it is valuable to walk through the entire API use case just as if you were a developer. So, the early sections of the API course set up new technical writers to do just that, and only then do they learn the best practices for writing and assuring the quality of the API documentation.

After investigating the API documentation course, there are plenty of other areas of I’d Rather Be Writing suitable for perusing on a Sunday morning over coffee.