You must understand the users of your application well to create documents for them. This post covers the principles required effective communcation.
In the first part, I will demonstrate some of the common errors, we as technical writers make, especially in the beginning of our careers. In the next part, I will list down some of the common principles for effective technical communication.
What annoys the reader?
Unclear introductions and conclusions: “I have read this tutorial, now what? What do I achieve reading this?”
Too much or too less detail: “Why some areas are over emphasized? Why does some content seem peripheral?”
Long sentences, jumbled expressions: “Why does this paragraph contain a single line? It is so wordy and time consuming. It has distorted my knowledge on the subject.”
Improper use of technical terms and concepts: “Why are the jargons misplaced?”
Writing flaws: “Messy document. The writer should have checked the document for consistency, grammar, etc before shipping. ”
Though writing is a subjective stream, there are certain facts which remain. You must always take up such challenges from your readers in form of feedback. This will help you to understand the mindset of readers and thus improve your skill set. In the next post, I will demonstrate the 7 habits of highly effective technical writer.
In the first part, I will demonstrate some of the common errors, we as technical writers make, especially in the beginning of our careers. In the next part, I will list down some of the common principles for effective technical communication.
What annoys the reader?
Vague purpose or context: "What is this write-up trying to convey? How does it fit in the larger picture? "
- You must make sure the information you are providing is not isolated. It should be appear as part of a complete guide or help. Such errors are encountered in topic based authoring.
- You must plan your content creation in a logical manner. For example, you may not want to provide explanation about a specific matter before introducing it.
Unclear introductions and conclusions: “I have read this tutorial, now what? What do I achieve reading this?”
- You should clearly define the importance of the written content. You must include appropriate information about the goals in the introduction and conclusion of a topic.
Too much or too less detail: “Why some areas are over emphasized? Why does some content seem peripheral?”
- In no case should a writer try to hide information while writing about a subject. You must make sure that you have gathered enough knowledge about the matter and then prepare content. Simple topics should be explained being less verbose depending on your audience.
Long sentences, jumbled expressions: “Why does this paragraph contain a single line? It is so wordy and time consuming. It has distorted my knowledge on the subject.”
- You must try to write short and meaningful sentences. The reader should be able to make sense of the content at the end of each paragraph.
Improper use of technical terms and concepts: “Why are the jargons misplaced?”
- Do not try to demonstrate your technical expertise in your writing. The content is necessarily prepared for users who want to understand the subject well. So, explain the topic in relatively simple terms.
Writing flaws: “Messy document. The writer should have checked the document for consistency, grammar, etc before shipping. ”
- Bad English or grammar errors can distract a user from the subject. You should recheck your content thoroughly before sending it out to the users.
Though writing is a subjective stream, there are certain facts which remain. You must always take up such challenges from your readers in form of feedback. This will help you to understand the mindset of readers and thus improve your skill set. In the next post, I will demonstrate the 7 habits of highly effective technical writer.
No comments:
Post a Comment