How I write docs quickly

I’ve been writing documentation and technical articles for more than a decade now. One piece of feedback I consistently got from managers and peers during all these years is how fast I am when producing and releasing docs. For example, I was once asked to document a new feature from a team I wasn’t serving two weeks ahead of launch. Everything was new to me, but I had most of the docs drafted after four days. By launch, the docs had been deemed ready to go live.

Would I have been able to write them better if I had been in the loop since development started? Perhaps, but software development often flows and ebbs in sudden and unpredictable ways: writing docs faster helps you adapt to deadlines. Would asking for more time or refusing to work on those docs given the short notice have been feasible? Maybe… but then the feature would have gone live with no docs, or the launch would have been postponed due to docs being required.

Being able to write those docs quickly made all the difference. In a world where software lasts a few years and new features are developed at breakneck pace, speed matters more than anything else. Going fast, though, doesn’t mean you’ve to sacrifice quality; it’s more about the right tradeoffs and learning how to use the resources at your disposal. Inspired by Evan Hahn’s How I build software quickly, I’m going to share some lessons I learned on how to write docs quickly.

If you go too fast, your work is buggy and hard to maintain. If you go too slowly, nothing gets shipped.

– Evan Hahn

Why write docs quickly? Accepting the inevitability of inaccuracy

I can hear some of you mumbling in the back rows: “Hasty work is low quality work! Accuracy is the most important aspect of our job.” Well, yes… but no. While haste and speed often get confused, they differ in that the second shows control instead of panic. You can maximize speed while keeping accuracy quite high; beyond a certain point, though, spending more time on accuracy, style, or other aspects that prevent a document from going live always yields diminishing returns.

Nobody reads perfect yet outdated docs, except historians. Even then, docs aren’t perfect, because documentation can’t ever be perfect. This is a key principle I stand by (call it the Ferri Paradox if you want): Any document describing a system is necessarily inaccurate. And yet, this reality doesn’t significantly alter the impact of our work, because we aim for simplicity and usefulness over extreme faithfulness. Given how imperfect products are, docs are a charitable portrait.

Now, how you write docs quickly depends on a number of factors. Some of those factors you can’t control: your overall amount of experience as a writer, your initial expertise with specific technologies, and the way features are developed and released in your organization. But other aspects are yours to act upon. For example, you can decide how to best use the technical resources at your disposal and how to approach writing the docs and asking for feedback.

Aim for Minimum Viable Documentation, then iterate and expand

Technical documentation is a representation of a technological product that can be interpreted and followed by users and, in the case of software, also by machines. The finishness of documentation is purely consensual: inventors and writers get together to decide when the docs are sufficient for the case at hand. In other words, documenting is a social process where one writer and one creator need to agree on scope, quality, and so on. Writers alone can’t decide what product truth is like.

This is where Minimum Viable Documentation (MVD), a concept introduced by Neil Kaplan at WtD 2018, comes in handy. MVD, much like a Minimum Viable Product, describes the minimum amount of docs, of good enough quality, that allow people to use a product. Think of it as a prototype or beta version, the dune buggy equivalent of the kind of finished car you want your docs to be. If the feeling of creating useful yet imperfect docs bothers you, read Sarah Moir’s words on the matter:

Something good is better than something chaotic and unhelpful, and it’s much better than no documentation at all. It’s also easier to focus on getting to minimum viable documentation rather than trying to reach full-featured documentation as soon as possible, because you’re a human with a life that is not your job.

There are many ways of producing MVD, but they all share the same pragmatic emphasis on planning for impact, getting something out of the door quickly to get feedback, and iterating afterwards. In The Columbo Technique for Technical Writers I described my own method for extracting information from stakeholders and requesting feedback. I also introduced the concept of Not-viable-enough docs, which you’d see as the step previous to creating MVD:

Not-viable-enough documentation is often a result of underlying product issues, which are excellent material for conversations with SMEs. Sometimes, even if they can’t be solved, they can lead to palliative docs care, that is, docs that help users cope with reality. It’s a win-win situation in that you’re helping users use the product, and SMEs avoid backslashes.

Put the quality assurance helmet on and get ready for adventure

The moment when he first approached me to clarify some installation instructions I provided for a user manual is unforgettable. Fabri just went ahead and tried it, and it did not work because I made an error! I felt very embarrassed but also deeply grateful!

— Gleb Smirnov

Nothing quite beats testing a feature or piece of technology yourself. The time spent getting first-hand experience of the thing you need to document is never wasted. This is also what should be expected from a documentation engineer these days: that you test and document the product using the same tools and methods as the developers you work with. While direct testing is not always possible, it provides the kind of hands-on knowledge that accelerates writing. You write because you know.

Over the years, I’ve come to terms with the fact that product truth can only be found in the struggle, not in the specs. Try to break things, get lost in the UI, feel the subtle sting of a confusing error message. Every bug you uncover, every awkward workflow you map out, is your entry into the engineering circle as a fellow tester. This is how you become a true devling: someone who speaks the language, understands the pain, and has earned their place in the conversation about quality.

Use docs UI features to your advantage and extend them if needed

Knowing your documentation tooling well can help you write better docs faster. I’m not referring here to the basic markup you’re using, but to the affordances that are built into the user interface of your docs, such as tabs, code snippets, and so on. A document can be more effective and faster to produce if you can structure it to take advantage of features that improve how information is presented. Accordions, for example, unlock progressive disclosure, if you have them and know how to use them.

If your docs platform lacks these elements and you can contribute code to it, you can try and add them yourself with the help of a fellow developer or an AI-powered code editor. I did this once to unlock some docs that sorely needed them. How did that make me save time? A satisfactory outcome would not have been possible otherwise, or would have required an approach such that writing time would have doubled (read: I would have needed to duplicate content).

Augment yourself through templates, linters, and AI-powered editors

Fabri impressed me first with his ability to create clear, customer-focused documentation at a break-neck pace. Beyond his writing skills, Fabri also demonstrated remarkable initiative by creating internal tools that streamlined the editing process for writers and editors alike.

– Alyssa Yell

The right tools won’t make you grow as a tech writer, but they can make you faster. There are many types of tools you can lean on, each bringing unique benefits when it comes to increasing your speed.

Here’s an example of what I mean by tools making you faster. This is a demo of Windsurf’s autocomplete capabilities when editing Markdown. If you know where you’re going, AI can help you get there in less time. In this case, its ability to detect patterns in your edits can save you hours every week. See for yourself:

Rely on people: you’re faster when working well with others

People can help you in so many ways, from approving a pull request to spotting typos in your drafts to redefine requirements together. As I said earlier, documenting is a social process; to do it right, and do it fast, you need to trust people and earn their trust, which is something you get when you know how to work well with others. You may be a lone writer, but you’re still part of a wider organization, with folks needing your help as much as you needing theirs.

The fastest writers I know are the ones who’ve figured out how to build the right relationships. They know which developer will give them straight answers about edge cases, which product manager actually understands user workflows, and which support team member has heard every possible complaint. More importantly, they’ve invested time in making those people’s lives easier, whether that’s catching bugs early, or simply being someone who responds quickly and thoughtfully.

To be a fast tech writer, you want to become the kind of collaborator people want to help succeed.