Modern technical writing - Andrew Etter 2016

Don't write
Basics

Like all writers, technical writers aim to produce content that their intended audiences will read and find useful¹. This has to be the goal, because any other goal is absurd. Keeping it in your head at all times will help you produce more valuable work in any profession. Consider a few common misconceptions about technical writers:

· Technical writers produce formal documentation.

In this case, "formal" means unnecessarily stuffy and repetitive, the sort of writing that causes people to skim rather than read. When your ideal readers are tee shirt-clad software developers who mainline Hiball Energy and spend most of the year looking forward to Burning Man, it's safe to assume a more casual writing style.

Note

This does not give you license to write in an unprofessional or sloppy manner. Writing should not call attention to itself by being too formal or too casual. Occasionally reminding readers that human beings produced their documentation is fine. Making readers think that they are reading rough drafts is not.

· Technical writers produce comprehensive documentation.

Writing should be the minimum possible length. Oddly, most students learn this guideline in grade school and have forgotten it by grad school. If a help system must be truly comprehensive, it should be because readers will accept nothing less, which is untrue 99% of the time. Huge blocks of writing look intimidating, and excessive content waters down useful content. Identify what the audience actually needs to know, and include only that.

· Technical writers help protect companies from lawsuits.

No, lawyers do that, and believe me when I say that they're perfectly comfortable composing their own indecipherable text. Technical writers, at the absolute most, should collate legalese into their websites. You should take content verbatim from actual attorneys and spend no more time on it than it takes to press Ctrl + C and Ctrl + V. Then show them how to update the content themselves so that you can get back to your real job.

· Technical writers produce print documentation.

Any piece of print documentation should be an absolute minimalist Getting Started guide (complete with requisite legal boilerplate) that directs its recipients to a web page. People are comfortable typing www into a web browser if they need help.

Unfortunately, producing content that people will read and find useful is, like, really hard. Here are the basics.

Don't write

Don't write often, anyway. Technical writers, first and foremost, are testers and researchers. Your job is to know what people want to achieve and precisely how to achieve it. Communicating that knowledge is the last step of the process and really shouldn't comprise more than 10% of your time. When people say, "I was writing all day," they don't mean they were intermittently typing for eight straight hours. They mean they spent the entire day engaged in the writing process. And a big part of that process is installing, configuring, and testing software. In other words, learning.

Remember, the job of a technical writer is not to find bugs. Sure, you will find bugs, and if you're not aware of any, you probably don't know the product very well. You should also report these bugs to developers. But the main point of a technical writer performing testing is not to improve product quality, but to increase personal knowledge. Your testing should be centered around making you smarter. Once you have a complete grasp of how something works, you can stop. Unlike a tester, you don't have to go any further. You don't have to reproduce tricky issues or check for unforeseen regressions in functionality. This difference makes your testing less tedious and more selfish than that of a formal quality assurance process, but because the ultimate goal is to teach others the material, you can pretend to be an altruist.

Be sure to leverage all the wonderful writing that developers and testers produce, even if it's half-complete, riddled with typos, and on a wiki page entitled "integrating with shamrock =D." Check the source repository for any files named README.md, and run any scripts with the help argument. Google any underlying open source software. Check Wikipedia for unfamiliar terms. Take notes. The learning process is time-consuming, so don't be discouraged if your measurable output is essentially nil for days or even weeks after moving onto a new project.

Contrary to popular belief, there are all kinds of stupid questions, or at least ignorant ones. The goal of all this testing and research is to be mentally equipped to ask pointed, intelligent questions to business development, product development, quality assurance, customer support, and ideally, actual users. For business reasons, this last group might not be accessible, but try your best to get in touch with some of them.

Talking to people is an art. A tester might want to gripe about a useless or buggy feature, whereas a developer might anxiously justify architectural decisions. A product manager probably wants to discuss long-term vision and will be upset if you didn't schedule a meeting, whereas a salesperson might be perfectly happy to chat about user frustrations from adjacent bathroom stalls. A good rule of thumb is to treat everyone as busy individuals whose time is valuable, but another rule of thumb is to break this rule and be more of a jerk if an essential employee isn't giving you the information you need to do your job. Tailor your approach to the person, come prepared to meetings, batch your questions into related sets rather than bothering people every twenty minutes with individual questions, and thank everyone for their time. Your contribution to a project isn't immediately obvious, so try not to be put out if people aren't as forthcoming as you'd like. Technical writers need to be grinders, willing to slowly but surely chip away at the block of ignorance until a beautiful sculpture emerges—or something like that, anyway.

After all that testing and research, you have to verify everything that people told you through additional testing. Tedious, but essential. At this point, though, you're well on the way to defining your audience.