Top 3 Serial Killers of a Good Document ? Technical Writing ToolBox

Don?t kill me- says your document!

Whether you are writing a user?s guide, online help, or an installation guide, you always strive to convey a meaningful message to your intended audience.

However, the message often gets diluted and becomes meaningless due to a number of reasons. Of course, a writer may not put enough efforts in making a message meaningful but most of the time several external factors contribute in killing the effectiveness of a document. Let?s look at the top three factors that kill a good document:

1. Time Constraints

People want to get things done yesterday. Seriously, do you expect a writer to woosh a magic wand and generate a document out of nowhere? I have had memories of the almighty project manager, stubborn developers, and agile marketing people who pushed all the buttons they could push to make things happen at the?last?moment. Documentation, unfortunately, always gets pushed to the last moment. You get what you put in. Less time means that a writer will have to cut corners, there will still be typos?in the document and the?effectiveness of the document will be?severely compromised. Just like a cake, a document needs time to get baked. Half baked cakes and documents prepared in hurry have one common factor: they stink!

2. Lack of Corporate Standards

Styles Guides and Marketing Communication standards exists for a reason. They bring uniformity to the document and chapters of an online help developed by several writers seem?consistent. Just as different people speak in a different way, different people also write in a different way. A style guide acts as a catalyst and brings uniformity to the?documentation. It really doesn?t matters if you choose Microsoft Manual of Style, Chicago Manual of Style, APA, MLA, Read me First or an in-house developed style guide. What matters is that you follow a standard.

3. Insufficient Information

Technical Writers are information solution providers. They take complex information as an input and generate easy to read documents as an output. However, if the input is insufficient then the quality of output cannot be good.

I know few unfortunate writers who worked in Agile teams where there were no string of information passed to the writer and yet S/He was responsible for generating the documentation. There is no functional specification, there is no example code and the developer has no time to talk. Well? even the software dialog you have to document doesn?t appears in the?software?build. Sounds familiar?

I have gone through similar instances where there was no or insufficient information available and I was?responsible?to develop an ?effective? document. I created my own cheat-sheet and methods to compensate for the lack of information. For example, I put a notification on a code repository where developers were checking?their?code. Whenever they used to check in code for modules which I was watching (and documenting), I used to get an email notification and I could guess the areas of change (new screenshots for new features, yay!). ?I was lucky and this?trick?worked but how many times can we be ?lucky??

What do you think are the factors that destroy effectiveness of a document? Can we do anything to make documents effective even without the availability of required time and information? Leave a comment and let me know.

Image(s): FreeDigitalPhotos.net

Like this:

One blogger likes this post.

splunk dark shadows iau msft etan patz obama dog doug hutchison