While thinking about unconventional technical communication, like comic books, children stories, and games, a thought occurred to me that they’re all attempts at hitting the core of what a product is and does, that is, its truth. I developed this picture of a series of concentric levels of comprehension and something resembling the circles of Dante’s Inferno came out of it. Don’t run away yet: Embrace hope all ye who enter here.
As a psychologist, I’m quite familiar with Maslow’s hierarchy of needs. It’s an extremely popular framework for human motivation. The hierarchy, often pictured as a pyramid, states that people look for certain things following a certain order: First shelter, then food, then company, etc. As with most psychological theories, Maslow’s is almost certainly false; nonetheless, it provides a very intuitive way of thinking about priorities.
There’s a string of questions that haunt every technical writer and documentation manager at some point in their careers: How do we know that we’ve done a good job? Have we been successful given our limited resources? How can we get better at what we do? Are the docs nailing it? How can we measure value? What do we tell upper management? More importantly, will we know what we’re saying when presenting those figures in slides? And, can you point me to the nearest emergency exit?
I wanted to write this post for a long time, but got to it only now, perhaps because it’s a natural segue into Let’s blog more about technical writing. Whatever the reason, I’m in a moment of my life where I feel compelled to say out loud why I love technical writing. Perhaps you’ll find some words of inspiration here. Or maybe not.
I’ve been wondering for a while why I don’t see more blogs on technical writing, tech comms, and technical documentation. I’ve been in listening mode for years, and beyond Tom Johnson’s excellent blog, it’s hard to find more content around technical writing. I’ve some hypotheses as to why that’s happening, as well as a request: We should be blogging more about technical writing and tech comms.
Prose linters are great at checking documentation against style guides, either in code editors or when running a CI/CD pipeline. They can capture issues in your docs that might have been overlooked by reviewers, thus avoiding costly mistakes. The bigger problem is how to bring the value of linters to our day-to-day jobs. How do you persuade colleagues to use them when drafting docs? It takes a little patience and ingenuity.
As a technical writer, I often want to know what works and what doesn’t in the docs I’ve released. Oftentimes, I also want to know if the documentation is achieving its purpose. There’s a very good way of getting answers about the quality of your documentation, and that is user research. Analytics or feedback widgets can only get you so far.
Beholding Stripe’s excellent documentation and wondering how they’ve built it is a modern technical writing trope. It’s no wonder, then, that when Stripe announced that they open sourced their documentation format and framework, Markdoc, folks would get psyched. I, too, was startled by the sudden release. After some initial doubts, I came to love their approach.
A few months ago, I drafted a technical writing syllabus. It features all the topics that a senior technical writer should master at some point when working on software documentation.
It’s my ritual: every time I enter a secondhand bookshop, I go straight to the Sciences section and search for old computer manuals. They’re very hard to come by, as their owners tend to throw them away once they stop using a particular device or piece of software. Manuals also happen not to be the most engaging read for most people, which adds to their rarity; few want to peruse an old IBM AS/400 handbook while laying at the beach.
Almost two years passed since I published my tips for working remotely. Now that remote work has become almost standard in the software industry, I felt like revisiting that list to add a few items. Enjoy!
Despite the massive growth of docs-as-code as a documentation ethos, I continue to be surprised, year after year, by the lack of robust docs-as-code tools. Most days it feels as if docs-as-code was a giant standing on feet of clay, on the fragile toolchains that we use to create our documentation in all kinds of software companies, from startups to unicorns.
A colleague asked me the other day what’s my favourite way of extracting information from subject-matter experts (SMEs). This is a big topic in technical writing, as most of our time at work is spent chasing engineers and project managers to get bits of information.
My answer was “Be like Lieutenant Columbo”.
The programmatic equivalent of UX Writing is API Design. The words that you use to describe your API enable conversations between software and people - it’s just a bit more structured and mechanical. That’s why technical writers are uniquely suited to assist technical teams in doing API design, especially when an API First design approach is being followed.
I get it. It’s hard to read articles about OpenAI’s coding and writing skills without feeling a shiver of neo-luddite panic running down your spine. Especially when one reads passages like the following.
A hands-on review of the most recent open source API documentation toolchains, such as ReDoc, Widdershins, and Elements, the newest solutions from Stoplight, among others. Get the slides here.
Code linters support developers by catching errors and stylistic issues in code, such as bad formatting or keywords in the wrong places. The term comes from lint traps in dryer machines, which capture the tiny bits of fiber that separate from cloth.
There was this discussion at work regarding docs in products, so I sketched a diagram to illustrate the main types of embedded docs, and their place in the product writing continuum, from UX writing to technical writing.
I’ve been working with remote teams for years. It didn’t always work well; sometimes the reason was the content I sent, but most of the time it was the content I did not send, the missed opportunities. The tool never mattered.
Now I want to share what I’ve learned from my past mistakes. Whether you work from home, or work from an office and have colleagues working in other time zones, I hope you’ll find these tips helpful — they’ve been for me.
From time to time, people ask me about technical writing and the type of work I do. As not much is known about technical writing outside of the English-speaking world, I came up with a short answer. I hope you’ll find it useful.