Writing a manual or instruction booklet for new team members or customers is difficult. You want them to get acquainted with your product or service in a positive way, while providing them with valuable information. But you don’t want to bore them or scare them away with complicated details.
Most people don’t pick up a piece of technical writing and think, “Oh, what fun I’ll have reading this!” They read it because it’s necessary for them to do so. So, if you want your readers to easily and willingly follow your instructions or advice, there are some basic instructions you’ll need to follow yourself.
1. Thou Shalt Conduct Research About Thy Product or Service
If you’re writing a manual about how to use a new software, then use it yourself first. You should also consult the designers or engineers of a product you’re writing about so you know all its key features and how it was made. And if you’re writing about a new service, pretend you’re a new customer and role play with the person who will be providing you with the service so that you can see how the process works first-hand. If appropriate, conduct research about materials used to create products, as well as any case studies that might be relevant to a service.
2. Thou Shalt Organize Content in a Logical and Easy-to-Follow Layout
Before you begin writing, create an outline for your document that follows the same roadmap your readers will follow to use your product or service. For instance, you won’t want to highlight the functionalities of an online platform before a user has even set up his or her login information.
Always use lists when possible because they’re easy to skim and remember. Include a step-by-step format to break down more complicated processes and instructions. And never include large blocks of text that are hard to read.
3. Thou Shalt Determine Publishing Requirements Before Creating a Final Draft
Before you’re finished with your first draft, know where and how your document is going to be read by others. If your readers are on the web, be sure to create your document in a way that’s easy to view in a browser window or on a mobile device, and make sure it’s easy to download and save. And if it’s to be printed, think about how large the document will be. If it’s smaller than a standard piece of notebook paper, you’ll want to make the text and images on it larger so they’re legible.
4. Thou Shalt Write for Thine Audience
Understand what knowledge your intended audience already has and do your research about them ahead of time. You don’t want to write something that’s over their heads, but you shouldn’t write below their comprehension level either. Address readers as “you,” and refrain from including a lot of acronyms unless you also include a glossary.
5. Thou Shalt Communicate with Style
The style and voice you use when writing your technical document will begin to surface once you understand your audience, product, or service. If your audience is learning how to build a toy clown, there’s no reason you can’t make the instructions funny and enjoyable to read. Sometimes you’ll want to remain professional yet friendly, and other times you’ll want to establish a more authoritative tone. Verify your style matches what you’re writing about.
6. Thou Shalt Be Concise and Quickly Get to the Point
Remember, you’re not writing a complex philosophical inquiry, you’re writing a document that’s intended to help a group of people with specific tasks. Begin your document with the essential information (or make it very easy to find), and don’t use long-winded text. Shorten long sentences and delete information that isn’t vital.
7. Thou Shalt Use Direct and Plain Language
Your readers should easily comprehend what you’ve written, especially if their safety could be at risk. To be more direct and write plainly:
- Use shorter sentences.
- Don’t use the passive voice.
- Address your audience as “you.”
- Avoid industry jargon and ambiguous phrasing at all costs.
8. Thou Shalt Show Readers What They Need to Know with Visual Aids
Photos and diagrams are your friend when you’re comprising a technical document. If you find it difficult to explain in writing how to do something, then you should accompany what you’re explaining with visual aids or images. Including a link to an instructional video can be helpful too.
9. Thou Shalt Highlight all Applicable Legal Requirements
Prepare your readers for anything that could endanger them when using your product or service. Think about liability concerns and other hazards. And think of cyber security to ensure your readers are safe from online threats too.
10. Thou Shalt Have Someone Else Review Your Work
Once you publish a technical document, your reputation is at stake, as well as the potential safety and security of your readers. Always have someone else review your document before it’s published to make sure it’s accurate, as interesting as it can be, and easy to follow.
Technical writing doesn’t have to be a chore to read or write when you keep your audience in mind. When you keep them in mind while writing your document, you’ll effortlessly follow the ten commandments, and produce a helpful document.
