Technical Writing Skills

Teaching skills

When I speak of teaching skills, I mean the ways in which you organize and present information such that your audience, the people that will be using your documentation, can learn and understand the topic for which you are writing. Far too much documentation falls short of being useful because the information is poorly organized. This poor organization reflects an inability to teach the topic at hand, or worse yet it points to poor understanding of the topic itself. To organize and present information in a useful way, you need to be able to:

• Write in a way that facilitates learning
• Organize information into meaningful groupings

If you don't write in a way that facilitates learning, your audience will have no hope in learning what you are presenting. More often than not, if a user finds your documentation difficult to learn from, they'll ignore your documentation and seek answers elsewhere. In order to facilitate learning, you must understand your audience, and write for them. For instance, if you are writing about 3D graphics software, you should use terms that 3D graphics artists use and understand. Getting to know your audience is a topic for another article, so for now all I'll say is that it often involves conducting user groups and interviews.

While there are many kinds of documentation that serve a variety of purposes, the general goal for all documentation is to explain something. Key to this is the ability to organize the information in such a way that makes sense to the reader, the ability to make the information easily accessible, and the ability to include only the information the reader needs. How many times have you been reading through a manual and wondered why chapters or headings were grouped in the way they were? This sort of mistake points to a misunderstanding about how the information should be organized.

 

---