Stay updated
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 6,100+ subscribers. (See email archive here.)

Search results

I'd Rather Be Writing blog

Finding a focus
I've been trying to think of a good focus for upcoming presentations and my blog lately, but I'm unsure about topics. I've focused on many topics in the past: trends, API documentation, docs-as-code tools, and before this, other areas such as blogging, podcasting, quick reference guides, value arguments, visuals, user-centered docs, and more. Ideally, I'd like to turn over a new leaf with some engaging topic that I've never explored before, but I'm not sure what that would be.
Updated API Getting Started tutorial
I updated the Getting Started tutorial section in my API course. I included a new section about the philosophic foundations of getting started tutorials, as I believe that this mindset toward action-oriented learning in API documentation is key. I also realized that the Run in Postman buttons are now forked collections in a web interface rather than static code that is downloaded to a local Postman client. So much changes in API tools that from one year to the next, any tutorial is sure to become outdated.
Technical writing course Q&A -- 'Become a Technical Writer', with Bobby Kennedy
Technical writing courses are popular ways for people transitioning into technical writing careers to build their skills, become familiar with the technical writing profession, and ultimately transition into jobs as technical writers. I had a chance to chat with Bobby Kennedy, a professional technical writer based in New York, who recently created a technical writing course called Become a Technical Writer.
Updated Stoplight tutorial
I updated (almost entirely rewrote) the tutorial for using Stoplight Studio. This is one of the centerpieces in my API doc course because it provides an easy way to create an OpenAPI specification document, without having to be familiar with the OpenAPI syntax or YAML.
Switching from Skype to Zoom for podcasting tools
I'm switching from Skype to Zoom for podcasting tools. Skype seems to be part of another era. The switch to Zoom opens up opportunities for another type of content -- one where participants share their screen more.
Videocast: Micro content and Flare -- Conversation with Kate Schneider
In this videocast, I chat with Kate Schneider about micro content and Flare. Kate shares micro content examples from her current documentation and explains the strategies she considers when creating micro content. She shows specifically how to leverage analytics in determining micro content topics.
Updated glossary article with technical examples [API doc course]
I revisited the original page on glossaries in my API doc course -- see API glossaries -- and expanded the content with many technical examples about how to single source glossary content from a single YAML file. I added examples for integrating tooltips and popovers as well, added more discussion, analysis, additional reading, and other updates overall. Although this page appears within my API course, the content could be applied to non-API docs and sites as well.
My life story, or reflections on what shaped my life's career trajectory
The paths I took in life depend in part of the family dynamics of my childhood, my interest in writing, and a career in tech. In this post, I try to trace the lines from my childhood to present day to understand what pulled me in the directions I took.
Analyzing doc portals by looking at developer journeys -- recommended podcast episode from Cherryleaf
Podcast 104 - Fixing broken developer portals, in Ellis Pratt's Cherryleaf podcast, is well worth listening to. Ellis explains a strategy of analyzing developer portals by looking at the developer journeys within the portal and identifying gaps or friction points in that journey.
Who can make documentation requests
In my API course, I defined intake processes for large documentation projects and small requests. However, I recently realized a major flaw in the process for small doc requests -- who can make the documentation request. In a nutshell, if you let anyone make doc requests, you can end up saddled with tasks to create documentation for which you lack information. If you instead require product teams to make the requests, you're more likely to get the information you need upfront.
Some good decisions and minor mistakes
During my transition time between Amazon and Google, I decided to create a brief list of some good decisions and minor mistakes during my five years at Amazon. This is a brief list, without much elaboration, but I think it's still valuable.
10 observations after using my API documentation checklist in a real scenario
I recently published a comprehensive checklist for evaluating documentation quality (the section starts here). In this section, I noted that my perspective is more evolving and experiential, which was good to note because when I tried to actually use the checklist, I realized a few shortcomings that I needed to address. Here are my 10 observations.
Adding last modified timestamps to content
Recently I received feedback from someone saying that they couldn't tell when my API documentation quality checklist article was published. This was embarrassing to me because printing timestamps on pages was one of the quality characteristics in the checklist. So I decided to add last-modified timestamps to every page. Unfortunately, this is a much harder task than it initially seems.
Product overviews -- a tricky space where documentation and marketing overlap
I recently re-wrote the article about product overviews in my API docs course, giving the article much more depth and discussion. I also included a survey to gather your feedback about my viewpoints with the product overview.
Q&A about Xeditor -- online XML editor -- with founder Matthias Kraus
A few years ago, I posted an article about Xeditor titled Xeditor, a CMS editor for XML content. In this post, I follow up about Xeditor with a Q&A with the founder, Matthias Kraus. The exchange here goes in-depth about Xeditor's origins, audience, latest enhancements, roadmap, and more.