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:
Like Loading...
Related
Technical Writing ToolBox 
There is a place for the “inventory of buttons and responses’ type of content. However, end-users what to know benefits first then features. For example, and end-user knows that they want to obtain certain results R1, R2 … Rn. What are the steps to obtain each result? If there are multiple paths to a given result, why might one select Pa over Pb or … Pz? New or novice end users might benefit from explanations behind R1, … Rn — Why might one want these results in the first place?
With the advent of post-processing applications that read the source code to extract details,
too often the best we get is the “inventory” document because it gets generated. Further,
the advent of semi-automatic language translation often adds entropy to an already mediocre inventory.
The “developers [ don’t have — won’t take — are not allowed ] time” situation is more and more common leaving end-user oriented documentation a less-than-poor step child of too many projects.
~~~ 0;-Dan
35+ year developer, team and project lead
~ 5 year technical writer
I agree entirely, documentation is always the last thing to be attended to and always needed by yesterday. It is a case of trying to educate the designers that we need the information as soon possible. Getting the information early is also inherent with problems as often the design changes and we are not informed. I always attempt to carry out a final evaluation of the technical content once the desig has been finalised.
DaveB
Thanks for sharing your thoughts Dave. It’s a good practice to evaluate the content after the design is finalised.
Hi Dan,
Thanks for sharing your thoughts. I’ve been a strong supporter of application/example based documentation in which we describe application of the products rather than its features. Unfortunately, most of the product accompany with list of features without providing any examples to use that technology/product.
I wish we can find a way to get rid of the “don’t have — won’t take — are not allowed” time situation.
Pingback: 7 causes of Inefficient Writing « Technical Writing ToolBox
Document length kills documents — or at very least their value. Sometimes it’s unavoidable, and a small minority of people love (or think they love) a hand-thick document, but the fact is that most people are too busy to try and wrangle such a beast. Most people want or need to be able to absorb information quickly. Writing any document past a certain size is like using up all the groceries in the house in a single meal: nobody is going to finish it, and nor should you expect them to.
Pingback: First Blog Post! – Brinley Arnou, Technical Writer
Pingback: Entry # 4: Resources for Technical Writing – Technical Writing Insider