Effective Technical Writing

In over a decade of my technical writing experience, I have been rather amused to see how newbie technical writers execute their duties as a professional technical writer. Ironically although they possess knowledge of technical writing tools like Adobe Frame Maker or Robohelp, along with inborn writing skills, still somewhere they get lost when it comes to producing a well ‘constructed’ user guide or online help!

Yup, the word is ‘getting lost’! Many less experienced technical writer often forgot the fact that above all of their tools knowledge and writing skills, the most crucial aspect is ‘well constructed composition’! Many times even for small screens or modules, I have seen writers simply writing and writing without realizing the importance of ‘well organized composition’ of the content.

So what is well organized composition and how to achieve this goal? Well the answer is simple – trash the unwanted, focus ONLY on what is to be conveyed to the end user, and decide the most crucial element of all – the approach! As a technical writer you have to come up with a ‘approach’ that would help you organize and present the content of your document in a highly effective manner. For example, you have one new field that is being added to 10 screens. So you have to decide the approach on how are you going to present this new field to the end user? Are you going to mention it 10 times for all 10 screens? Or are you simply going to create a new chapter mentioning this new field and then simply place a reference link in all 10 screen chapter? Well the shorter, simpler and crispier is your approach, the better! Because users are impatient and want to have information as quick as possible! The best thing that the tools offer is the facility to add reference links! Reference links allows you to minimize the repetition of content and the length of your user guide as well! What is necessary to understand is when you write a user guide, you are providing information and at the same time you also are instructing the user on how to perform a specific function! So it is necessary that you gel both of these aspects and then present it in the simplest manner possible!

Remember as a technical writer you should understand that your end user is your student! He or she is completely unaware of the features that are you going to write about and hence it is very important for you to think of all aspects that will help you present your ‘story’ to the end user in the most effective manner. Well imagine or rather consider yourself as the Director of a movie! Yup, the movie (software) is written (coded) by the programmer, and now it is YOU who have been given this magnanimous task of ‘presenting’ this movie to the end user! So guess what would be your first stand? As a Director, the very first task would be to decide on ‘how to present’ this movie? What should be the ‘approach’? Many times a movie that has to be directed has many complicated sequences, just the way the software has many complicated screens or fields! But a seasoned Director knows how to present such complicated movies in a most effective manner! This is because he is a good analyzer! He breaks every aspect of the movie in bits and pieces, and then he analysis each piece of the movie and then comes up with a finalized approach! Similarly as a technical writer you have to break a module into pieces, analyze each of the screens and then come up with a finalized TOC (table of contents)! Once your table of contents is finalized then you are all set to start up with writing on each of the chapters!

READ  HOW TO: Root the HTC Desire (Updated, Easier Method)

Table of Contents is the blueprint of your approach! It displays How and Where you are going to mention features and functionalities of each module! Think like a ‘teacher’ or rather like a ‘friend’ when you write a user guide! Just imagine if your end user is standing next to you and asking you on ‘how to do, what to do, to get a desired outcome’ then how would you explain? Wouldn’t you try to explain it in the most easily understandable way? Wouldn’t you give one or two example, or demonstrations? Well certainly you would! So that is how you have to be when you are writing a user guide! Always imagine that your end user is standing next to you and asking you about a feature of the software and then start writing so that when you write you will be more sensitive to the end user needs and expectations! And eventually you will generate the most effective and usable user guide!

Thus to become an effective technical writer, some of the crucial aspects that you need to understand and implement are:

Analyze the features

Do not overload yourself with too much of information

Use only that information which needs to be conveyed in the user guide

Work on the ‘Approach’, try to ‘present’ the gathered information in simple, shorter and quicker way

Use Reference links wisely so as to minimize the repetition of content and as well as to generate a compact user guide which is not lengthy and boring!

 

Leave a Reply

Your email address will not be published. Required fields are marked *