stories from the suburbs, or something.
stories from the suburbs, or something.
I've found myself swallowed into a sudden, intense focus on our documentation at work. This is because the documentation we previously had was inadequate, slipshod, at various levels of technical detail, containing huge gaps in information and in some sections, outright incomprehensible. Yup, it was bad. So bad, that in previous releases, nothing had ever been done about it because... where to start?
Well, the Powers That Be have finally sat up and taken notice (probably because we're about to start having real customers (heavens!)) and are now demanding real and proper documentation. Stuff which is meaningful, coherent, written for the right audience. This has basically entailed a complete rewrite.
Now, anyone who knows me, knows that I just don't deal well with foolish people, and that I fall asleep if I have to read a non-fiction book (unless it's a LonelyPlanet guide). And here I am writing documentation.
So in contrast with Fleur, who never saw herself as a fiction writer but is now doing good Writing Works, I always figured I'd write fiction (whether as a hobby or perhaps even for real dollario) and here I am writing technical documentation. Come to think of it, in the dim dark murky past I've even been paid for writing technical documentation. And yet the thought of doing it full time fills me with horror.
I blame El Nino. (It seems to get blamed for everything else). And if not El Nino, then the hole in the ozone layer.
Do you reckon there's a fundamental split between documenters and non-documenters? You know, between folks who will just look at you and say "if you can't understand it then documentation won't help you" and folks who say "I'm not looking at anything until you tell me what I'm looking at". In my experience, there are some gender divisions here as well. But then, I make my living practising a fallen art: neither fiction nor non-fiction, simply policy argument and descriptions of systems.
posted on September 19, 2002 4:28 PM by darren.I certainly reckon such a split exists. But I think both sets of arguments have a place, regardless of what it is you're attempting to write about.
To begin with: design your 'thing' (whether it's software, hardware, a process, travel brochure, ...) with the theory that people just won't need documentation to understand it.
Then: recognise that people are fallible, forgetful, and there's going to be about 20% (more or less) of your 'thing' which will be esoteric/complicated/less frequently used and thus people won't remember it on the spot. So you'll need a manual for it (whether explanatory or just reference).
My travel brochures have the fine print up the back about cancellation conditions, what to bring on certain tours. My software help files come with a tedious reference on all the sets of properties you can edit if you were Really That Keen. I don't read the manual to drive my car, but I will check it again before inflating my tyres, just to check the recommended psi.
posted on September 20, 2002 8:13 AM by nicola.