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? Read more »

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. Read more »

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. Read more »

From monkey mind to calm, ordered consciousness -- even outside of flow? Wrestling with Csikszentmihalyi's assumptions about psychic entropy

This post continues my series about how to regain long-form concentration. Although Csikszentmihalyi says the brain's natural state — when left alone without any focused attention — gravitates toward entropy and chaos (more commonly referred to as monkey mind), I'm not sure I want to agree. In this post, I ask how and why consciousness becomes disordered in the first place (why we have monkey mind), and how we might change that natural state. In my experience, infinite-scrolling the web and filling my mind with a high-intensity of randomness creates different brain patterns than reading a book. (Note: Admittedly, in this post, I go off the deep end a bit.) Read more »

Applying Csikszentmihalyi's psychology of flow to the writing of technical documentation

Mihaly Csikszentmihalyi's psychology of flow, which describes ways to be so engrossed in an activity that you lose track of time, can be applied to writing technical documentation. Some of the traits of flow I cover here include balance, effortlessness, goals, feedback, and concentration. Read more »

How to move from focus sessions to flow sessions

In this post, I describe my experience in trying to complete several ninety-minute focus sessions a day. While they allowed me to make a lot of progress, they reduced some of the fun from writing. This post is part of my ongoing series Journey away from smartphones. Read 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. Read more »