When I first started out in this industry I received little direction other than “make sure you check everything” so a lot of my original ideas of how I should work and what documentation should cover were largely my own. I looked at manuals for a variety of applications and took ideas from them, adapting them for my own use, initially focussing on the structure and presentation rather than the content itself. It was this approach that was my downfall.
Actually, that’s not true. Lack of understanding of my audience was my downfall but I didn’t realise that at the time. Instead I took the “ohh that’s neat” ideas from a variety of other sources and wedged them into my documentation. What that left me with was too much content, which is almost as bad as too little, with every detail about the application covered from three or four different angles, leaving the reader confused and bewildered as they tried to figure out what they SHOULD be doing rather than what they COULD.
It wasn’t until I met one of the users, by chance, and spent some time with her that I realised (some of) the error of my ways.
These days, with a better understanding of my profession and a strong understanding of our audience, I find myself writing documentation that is just enough. Am I selling the audience short? I don’t think so, and so far none of the feedback I’ve had has stated that they didn’t have enough ‘words on the page’, although that’s largely because “Just enough” doesn’t mean “this will do”. Perhaps I need to use a different phrase…
Whilst you can over-document a product and there are always edge cases of usage that you rightly shouldn’t document, consideration of how that information is constructed and delivered not only benefits the reader, but can help you meet project demands. These days everyone is being pressured to produce more and deliver it faster, so being able to tackle work in increments, delivering smaller chunks of information more frequently, with the end goal of building them into a larger unit of content can only be a good thing.
Writing “just enough” information for a given topic fits just as well in a linear writing process as it does in single source. You get similar benefits in that you can quickly flesh out the basis of a document, then revisit each area to make it more complete. The draft and review process is one which we are all familiar with, but (and I wish I could go back and tell myself this 13 years ago!) it doesn’t mean write once, review often, quite the opposite.
One of the biggest lessons I’ve learned, the hard way, is not to be afraid of writing “just enough”, as long as it truly is enough to help your users.
