FAQ on Technical Writing
Technical writers create different types of documentation, for example, user manuals, API documentation, ?How to? guides and so on. I wrote an article on how to write a user manual, so today I?ll tell you about creating a ?How to? guide.
Planning the Guide
When you get a task to create a guide your first step should be planning. Here is what you should do:
Understand your target audience
When you start writing your guide, you should clearly understand who your target audience is. What is their age, what is their background and so on. This will define the style of your ?How to? guide on the most fundamental level ? the complexity of language used, the number of terms and many other characteristics.
Research on the process
I recommend that you read about other people?s experience in writing ?how-to? guides. It?ll help you get a clear image of future work, and you can integrate others? approaches into your working process. For example, I wrote about Amrute Ranade?s technical writing process, you can read the article here: ?Great Technical Writing Process?. So, you can also use this method to ease your technical writing.
Gather useful materials
Before you start writing, collect material and information that will help you write a ?how-to? guide. It can be additional information on a product, other ?how-to? guides on similar products or something else.
Write Your ?How-to? Guide
First of all, create a plan ? it will be easier to write a guide if you visualize it. After all these preparations, it?s high time to start writing. While creating a guide, you should keep in mind the following tips:
- Write in plain English to speak the same language as your readers.
- Your language should be always concise (e.g., ?Select the option? instead of ?You should select the option?).
- Create numbered lists to structure steps if a user needs to complete them
- Add visual content like photos, screenshots, and diagrams.
- Break content up into headed sections but write them clearly
- If you want to use jokes, be careful: people may not understand you
- Add mini-TOCs to make big topics more readable.
The most essential tip is the following ? spelling and grammar mistakes are unacceptable in the documentation, so thoroughly check your guide. Here is a list of Top Free Grammar Checkers. Also, you can ask someone else to proofread for you, or read your own steps in reverse to be sure that your writing is clear and simple. Here are a couple of other resources to write great documentation:
- Grammar Books for Technical Writers
- Style Guides for Technical Writers
Of course, that?s not everything there is to know about writing ?How to? guides, but these tips are the most essential, to my mind. I hope they help you.
Good luck with your writing guides!
