Chapter 1

Look before you write

Writing effective instructions is an achievement. Modern instructions shouldn’t just be a list of useful directions. They embrace the aesthetic and conventions of our time: highly visual, sleek, interactive, and well-designed. And when they’re done right, they’re a pathway to empowerment.

A fixed car

Right now, you’re probably excited to get writing. But before you start galloping off into the tech writing sunset, know this: most of the manuals and guides out there are written by people who have no firsthand knowledge of the subject matter. We think that’s a problem. It takes more than just writing skill to write a good manual: it also takes understanding. There are two laws of tech writing:

  1. Know thy product and process
  2. Talk to thy experts

Know thy Products and Process

The first requirement for tech writing is knowledge. You can’t teach someone how to do something until you’ve done it yourself. If you’re writing assembly instructions, put the product together. If you’re writing about software, use the program. If you’re writing a product manual, you should know the product inside and out. Use it, take it apart, figure out how it works and what it’s meant to do.

Once you think you know the process, try to teach it to someone else. Teaching is a great way to solidify your knowledge, and what you learn from watching your student struggle will make your manual better.

Talk to thy Experts

If you’re not an expert at what you’re writing about, talk to someone who is. Chat with the developers, technicians, or designers. Ask them to give you a walkthrough of the product, process, or software. Ask them how it’s made, how it’s done, and why things are the way they are. Then, keep asking if you need more help.

Glean as many stories from them as you can. Understanding the process that goes into making something will clarify your understanding.

How manuals are usually written

How manuals are usually written: Tech writers create a first draft based on initial functional specifications. Of course, the real product barely resembles the spec by the time the manual is written. The first draft is a total waste of time. As part of the frustrating review process, engineers give the writers hand-scribbled notes. Tech writers assemble another draft, which engineers promptly rip apart. And the process starts over again. Finally, the document is published.

But it doesn’t have to be that way. The faster and more frequent the interactions between engineer and writer, the better the final product will be.