So you want to be a good technical writer. Ok. But what does that entail? What is good technical writing vs. bad technical writing?
I’ve seen a lot of software engineers attempt to write help documentation. And a lot of companies try to save on cost by having them do so (not a good idea). During my career I have learned something very important: technical writing is a skill that must be developed, and not everyone is capable of good technical writing. And something else I have learned: you need to be a good writer, first and foremost, before you can be a good technical writer. You must have the skills to not only translate technically challenging information into common language, but to use the English language appropriately in pursuit of this goal.
So how can you become a better technical writer? Or better yet, want to know some technical writing basics? Here are some tips.
1. Know your audience. Are your end users technically savvy people? Or are computers completely foreign to them?
Knowing the answer to this question is important for determining how you need to present your material, and what level of detail you should provide. If you have a very savvy audience, then you can use more complex ideas and omit some basic information (such as, what a user name is). If you have a group of users who have never before accessed a computer, then you would need to go into more detail about basic use (i.e., explaining what a user name is) and you would want to omit information that is way above their knowledge level.
2. Use direct language. Tell them what to do. Use “click here to continue” rather than “the button should be clicked to continue”.
3. Get to the point. The worst technical documents are wordy, wordy, wordy. Good technical writers know how to condense their material into the shortest possible sentence/paragraph without losing meaning. This is not always an easy task, depending on your skill level. But do make an effort. For example:
Bad technical writing: Scroll to the bottom of the page and locate the Submit button, which you will then click to submit your information to the database.
Good technical writing: Click the Submit button at the bottom of the page to submit your information to the database.
What’s so bad about the first example? Wordy, bumbling, and indirect (“which you will then click”). What’s so good about the second example? Clear, to the point, and succinct.
You don’t need to tell the user to scroll down if you say that the button is at the bottom of the page. The user will know they need to scroll in order to get there. So take it out – it’s a waste of space and words.
More tips to come.
I’ve seen a lot of software engineers attempt to write help documentation. And a lot of companies try to save on cost by having them do so (not a good idea). During my career I have learned something very important: technical writing is a skill that must be developed, and not everyone is capable of good technical writing. And something else I have learned: you need to be a good writer, first and foremost, before you can be a good technical writer. You must have the skills to not only translate technically challenging information into common language, but to use the English language appropriately in pursuit of this goal.
So how can you become a better technical writer? Or better yet, want to know some technical writing basics? Here are some tips.
1. Know your audience. Are your end users technically savvy people? Or are computers completely foreign to them?
Knowing the answer to this question is important for determining how you need to present your material, and what level of detail you should provide. If you have a very savvy audience, then you can use more complex ideas and omit some basic information (such as, what a user name is). If you have a group of users who have never before accessed a computer, then you would need to go into more detail about basic use (i.e., explaining what a user name is) and you would want to omit information that is way above their knowledge level.
2. Use direct language. Tell them what to do. Use “click here to continue” rather than “the button should be clicked to continue”.
3. Get to the point. The worst technical documents are wordy, wordy, wordy. Good technical writers know how to condense their material into the shortest possible sentence/paragraph without losing meaning. This is not always an easy task, depending on your skill level. But do make an effort. For example:
Bad technical writing: Scroll to the bottom of the page and locate the Submit button, which you will then click to submit your information to the database.
Good technical writing: Click the Submit button at the bottom of the page to submit your information to the database.
What’s so bad about the first example? Wordy, bumbling, and indirect (“which you will then click”). What’s so good about the second example? Clear, to the point, and succinct.
You don’t need to tell the user to scroll down if you say that the button is at the bottom of the page. The user will know they need to scroll in order to get there. So take it out – it’s a waste of space and words.
More tips to come.
RSS Feed