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.
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 a 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.)
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.
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.
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.
Techniques for deep work from Cal Newport
In this post, I summarize the ideas from Cal Newport's popular book, Deep Work. Structuring your time into several periods of deep focus during the day can help you become wildly productive.
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.
From smartphones to Netflix: moving past plateaus in growth
In this post, I note that I've slowed reading a bit and started watching Netflix more. I turn to two system archetype theories to explain these dynamics. The archetypes 'Limits to Growth' and 'Shifting the Burden' from Peter Senge's The Fifth Discipline, a classic about learning organizations, provide insight into how to move past plateaus.
Driving without GPS — the desire to be free and in control
Driving is one way we exercise our freedom. Driving without GPS could be seen as a rejection of the control of technological algorithms over lives.
Spatial and scientific reasoning from wayfinding
The origins of scientific thinking probably developed with the first animal trackers, not just the Greeks. As we wayfind, we piece together inferences by reading the signs in the environment around us.
Wayfinding requires you to be present in the world
Wayfinding starts with being attentive and present with the world around you. However, our suburban geography-of-nowhere-type cementscapes remove a lot of incentive for attentiveness.