Pulling readers through long documents

Long, high-level conceptual docs don't command the same reading attention as task-based docs. How do you pull a reader through a long doc when the payoff isn't a completed task, but merely greater understanding?

Stoplight tutorial update -- practically every screenshot updated

One of the most popular tutorials in my API doc course is this getting started tutorial for Stoplight Studio. Stoplight Studio is a tool for creating the OpenAPI specification and generating both reference and tutorial documentation. I recently worked with Stoplight writers to update all the screenshots and other details that have changed over the past year. The tutorial is now fully up to date.

Podcast about Archbee -- a new documentation tool with a block-based editor, API publishing capability, content re-use, and more

Archbee is a relatively new documentation tool that offers a block-based editor, API publishing capability, content re-use, and more. The initial version of Archbee was released in early 2019. Since then, the product has been steadily ramping up in features and growing its customer base. In this podcast, I chat with Claudiu Dascalescu about Archbee, the features driving its adoption, their target audience, and more.

Attempting to write a Life of a [something] narrative

In this post, I describe an attempt at horizontal writing and what I learned from it. I was surprised to be struck with a kind of reverent awe for the complexity that this horizontal view revealed.

'Putting together things': Articulating a thesis about the effects of hyper-specialization on documentation

In this post, I try to articulate the emerging thesis in this series on fizzled trends. In a nutshell, my argument is that technical writers should focus on higher-level overview content in authoring technical content — for example, a systems view, developer journey, product overview, and the like. The reason being, the role of editing, curating, and publishing information as a valuable skill seem to be diminishing in importance. Additionally, with technology trends moving toward hyper-specialization, this larger, overarching system view is nearly extinct.

Expanding from cross-product newsletters to a book club and site

It's been a few months since I've added anything to this series (A hypothesis about influence on the web and the workplace), but the absence doesn't mean that I've abandoned the theme. Instead, I've been mulling over some new strategies that have taken a while to play out. I'm now ready to describe the most recent segment in this journey.

Some advice if you're just starting out your technical writing career

I recently spoke to some technical writing interns at my work on the topic of career advice. The topic was as follows: What advice would you give to those just starting out their technical writing career? Imagine turning back the clock 20 years. What advice would be most helpful? This post expands on some of these ideas. It also gave me an opportunity to play around with Midjourney, an art AI tool that automatically creates images based on text prompts. (For fun, I included the text prompts as captions.) Unlike my other posts, this post is more visual, as it was originally intended more as a slide deck than a blog post.

Systems thinking: Limits to Growth, Complex Cause and Effect, and Shifting the Burden

This post is part of a series that explores tech comm trends that I've either followed or forgotten, and why. In this post, I continue to unravel the principles of systems thinking and how this approach fits into the documentation domain. In particular, I dive into three system patterns covered in Peter Senge's book The Fifth Discipline: Limits to Growth, Complex Cause and Effect, and Shifting the Burden. And I try to connect the ideas back to documentation.

Systems thinking and developer portals

This post is part of a series that explores tech comm trends that I've either followed or forgotten, and why. In this post, I explore why focusing on the big picture fits into the domain of systems thinking. I also make a case for developer portals as a candidate for study that aligns with a systems thinking approach.

Blobr API portal (API doc topic)

I added a new article about Blobr to my API course. With Blobr, you can create an API store to launch and grow an API business with different monetization models. In the same Blobr portal, you can also include documentation that describes the precise workflow for each use case, helping API consumers easily onboard with your API.

The impact of technical diversity on documentation -- epiphanies on a trip to IKEA

This post is part of a series that explores tech comm trends that I've either followed or forgotten, and why. The overall goal is to better understand the reasons that drive trend adoption or abandonment in my personal career. This post focuses on the impact of diversity/pluralism/fragmentation on documentation.

Technical diversity/pluralism/fragmentation in tech comm

This post is part of a series that explores tech comm trends that I've either followed or forgotten, and why. The overall goal is to better understand the reasons that drive trend adoption or abandonment in my personal career. This post focuses on technical diversity/pluralism/fragmentation.

My Commute Seattle Spotlight

Recently I volunteered to have my multimodal commute spotlighted as part of a Commute Seattle campaign. Here's the video.

Review of Peter Norton's Autonorama: The Illusory Promise of High-Tech Driving

Peter Norton's Autonorama: The Illusion of High-Tech Driving is a must-read for anyone pursuing autonomous vehicles (AVs) as a solution to the problems of transportation mobility. Norton's main argument is that AVs will worsen rather than help transportation issues.

Docs as Code

This post is part of a series that explores tech comm trends that I've either followed or forgotten, and why. The overall goal is to better understand the reasons that drive trend adoption or abandonment in my personal career. This post focuses on Docs as Code.