Technical documentation is a critical part of any product. Its importance is often underestimated; top notch technical writers can make a huge difference to the success of a product family or business unit. They can provide a competitive advantage to an organization.
For many products, people often turn to the documentation when they’re tearing their hair out with frustration. Clear, simple, accurate instructions and tutorials that help customers to do what they’re trying to do can avert disaster, prevent product returns, and build brand loyalty. For the most technically complex products, the documentation is an essential starting point for understanding the product, its applications, and how to use it.
Over the years, I’ve created a great deal of technical documentation and worked with a lot of technical writers, both as a writer and as a manager, and I’ve given a lot of thought to what separates a great technical writer from the rest. So what makes a great technical writer?
The best writers have a clear, straightforward writing style
Some things are obvious. You can’t be a good technical writer without being able to write well, though you’d be surprised at how many people try. The best technical writers have an excellent grasp of the English language combined with a straightforward writing style.
In fact, top tier technical writers are generally quite capable of writing very complex sentences for other purposes (blog posts, for example), but when writing documentation, they arc towards clarity and precision over sophistication. There is a spare elegance to good technical writing.
Technical writers are curious about technology
Technical writers need to be very curious and genuinely interested in technology. While some would argue that a technical degree (particularly computer science) is of critical importance, I disagree. It’s not that it won’t help, at least in some contexts. You certainly can’t create API documentation or a programmer’s manual without a good understanding of what the code does and how it works. But as a rule, the crucial value proposition that a technical writer brings to the table is not the ability to write code but the ability to see that code from a different perspective, one that allows them to grapple with and explain how the customer should use the product.
A sufficiently intelligent, curious technical writer has an innate drive to understand new things, and can process a great deal of information very quickly. If that means learning a programming language in order to document an API, that’s what he or she will do.
Technical writers are organized, systematic, and analytical
An elite technical writer is very organized and systematic, with a deeply analytical mind and the ability to break things down into more and more manageable chunks. So much of the work is about creating consistent, complete libraries of information for complex technologies with many, many details.
At any given time, a writer should have a very clear idea of which pieces of the information are solid and which need work, which are higher priority and which can wait. This helps to align priorities and focus efforts for maximum impact.
They learn new writing tools and techniques quickly
Technical writers need the ability to quickly learn new writing tools. Some writers focus on a particular tool: MadCap Flare, say, or oXygen XML Editor. While the different tools in the market have strengths and weaknesses, for the most part they do many of the same things in slightly different ways, with varying degrees of success. A good writer is always picking up new tricks and adapting to the changing tools and software landscape depending on the needs and priorities of their employer.
It’s a common mistake when hiring writers to only consider ones who already have experience with the particular tools used for the project. The best writers learn tools very rapidly, and will soon outperform an average technical writer even in an entirely new tools landscape. That said, if the writer is being hired for a broader tools-related role, such as designing an XML/DITA content reuse strategy, it’s probably a good idea to hire someone with expertise in the relevant tools. (Of course, such strategies are often the domain of information architects, content strategists, and tools specialists.)
They’re open to new ideas and approaches
To excel in this field, a writer needs to be very open to new ideas and is constantly seeking better solutions. Technical writing is all about making the customer’s life easier, so the best are constantly seeking to improve the documentation and the product itself, with a keen eye for usability and a clear understanding of the product’s features and uses from the customer’s perspective. This leads the writer to ask a lot of salient and sometimes uncomfortable questions.
Should this document be available in a web format that is responsive for delivery to any device? Is this concept better taught through a set of short videos? Can we simplify the design of the user interface and eliminate the need for the documentation altogether, or use minimalist embedded documentation? Is there a simple set of instructions I can provide to get started? Can I do this work faster and more efficiently through single-sourcing and content reuse? Can I autogenerate this documentation from the code? Can this content be more integrated with the product and support framework to improve the customer experience? Do I need to restructure this content so that it really shows the user what they need to do?
To have a real impact on your organization’s success through documentation, writers must constantly ask these kinds of questions. They must be committed to making the documentation, the product, and the organization better.
One of the most important qualities of a top technical writer is more intangible. Everyone I know who really thrives in this field has a particular set of personality attributes, chief among them a sense of humor, a fairly easygoing demeanor, the ability to maintain composure in situations that can feel pretty daunting, and a highly professional approach to the work.
A technical writer deals with a lot of people in different roles and at different levels in an organization, from brilliant designers to the most gregarious marketing executive and the most demanding project manager. These people are all typically under a lot of pressure, and they usually don’t see the documentation as the most important thing on their list. Handling them all takes a light touch and a thick skin.
Writers are often subject to rapidly shifting requirements, tight deadlines, and a failure to appreciate the complexity of their work. It takes a lot of composure to navigate the players, roles, and often informal power relationships in an organization in order to get your work done and deliver high quality customer documentation on schedule.
Some writers can do this for a while, but eventually the wear and tear gets to them. The best learn how to keep moving forward while maintaining sanity, balance and perspective. They know how to laugh. They know how to keep meeting the company’s and the customer’s needs, sometimes during chaotic release cycles, all the while fixing the underlying problems that make it hard to produce good documentation in the first place. This takes an unusual mix of courage, determination, and diplomacy.
Technical writing is a complex, multidisciplinary field, and I could fill a book with thoughts about how to do it well. But basically, it comes down to this. Keep the customer in mind. Write well. Keep learning about technology. Adapt to new writing tools. Be flexible and creative. Stay calm and focused. Laugh. These are all skills and qualities that would serve any professional well, and the combination makes for a great technical writer.