In a technology world growing increasingly specialized, technical writers can stay relevant by leveraging their most salient skill: the ability to see the big picture, to look across systems or individual APIs and see the shape of the whole. Technical writers can employ big-picture thinking with docs by emphasizing the following content types: (1) Detailed product overviews, (2) developer journeys, (3) cross-system workflows, (4) integrated API data, (5) and external domain knowledge.
Bobby Kennedy provides various courses on becometechnicalwriter.com to help people transition into technical writing. Previously, he mostly offered eight-week Jump School courses. Starting this spring, he's also offering a new, one-of-a-kind course called the Job-Hunter Support Group, which focuses on helping people find job openings for technical writers, prepare a resume and portfolio, and interview convincingly for the positions. The following is a Q&A with Bobby about the new course. (Note: This is a sponsored post.)
I'm starting a new series called Sitting, standing, and walking. Near the end of my last series on Journey away from smartphones, I described the growing discontent I felt by sitting in front of a screen all day. I longed to be outside, walking, engrossed in a panoramic view of the surrounding sky. Instead, it seemed most of my life, especially working in tech, was spent sitting. This series is all about ways to reduce sitting and avoid a sedentary life in front of the screen.
Jeff Krinock and Matt Hoff's 2016 book, May I Ask a Technical Question? Questions about digital reliability each of us should ask, provides an essential addition to the growing cyber-skeptic genre. The authors don't aim to vilify digital technology, but rather to encourage readers to thoughtfully consider the costs and benefits of each innovation.
Whatever skill you outsource, atrophies. When we outsource tasks to machines to perform, our ability to perform the task ourselves weakens. From driving to writing, automation threatens to reduce key elements of the human experience. In this post, I'll use Matthew Crawford's Why We Drive as a lens through which to interpret ChatGPT. Although Crawford's book is about driving, so many of the arguments could equally apply to writing.
If you haven't already heard about and experimented with ChatGPT, you need to. This generative AI writing tool has the potential to do for writing what art AI tools have already done for graphic content. ChatGPT is pretty mind-blowing. I didn't realize AI writing tools were so advanced.
In my previous post, Pulling readers through long documents, I explained that almost no one will read long documents, in my experience. It seems only task-based information demands enough payoff to make reading worth it to users. In this post, I'll explore a couple of examples where high-level information is essential and used, but in another light. The two examples are Macbeth and Elon Musk.
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?
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.
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.
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.
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.
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.
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.
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.
