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 »
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 »
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 »
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 »
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 »
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 »
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 »