Custom development is that murky world where a customer tells you what to build, and you say, "are you sure?" and they say yes, and you make an absolutely beautiful spec, and say, "is this what you want?" and they say yes, and you make them sign the spec in indelible ink, nay, blood, and they do, and then you build that thing they signed off on, promptly, precisely and exactly, and they see it and they are horrified and shocked, and you spend the rest of the week reading up on whether your E&O insurance is going to cover the legal fees for the lawsuit you've gotten yourself into or merely the settlement cost. Or, if you're really lucky, the customer will smile wanly and put your code in a drawer and never use it again and never call you back.
Oh boy, does that ever hit close to home.
An interesting thing about technical writers is that while they are officially considered part of the sub-development world - on the same level with testers, sysadmins and the "last line of defense" support people, if you have any - programmers tend to think of them in the same vein as marketing and design people, creative types that produce beautiful things through a magical process. I can see where it's coming from - a good technical writer must be a good writer, and doesn't necessarily need to be a good technician; and good writing is indeed a creative process. If you don't need beautiful text, you don't get a tech writer. If all you need is very technical documentation only meant for developers, well, developers really much prefer to take care of it themselves, because they get to keep their own indecipherable conventions (which do work in this case). Or if you don't want to waste the dev's time, you get an intern studying CS to do it, because he's much cheaper.
The upshot is that a technical writer is expected to produce what the requester had in mind. The requester, usually a project manager or one of those people who holds the client's hand, has this Platonic ideal of a document, which they somehow manage to put into words and fob off to the writers. Often enough these people, especially if you haven't domesticated them yet, will honestly believe that the writer will use voodoo magic to extract the ideal document from the ethereal plains of purest knowledge and put it conveniently into a Word doc.
So if you're a tech writer, you inevitably arrive at the singular effective tactic for dealing with such requests. What you do is look at it, get a rough idea of what the point is, and put together a very crappy pre-alpha zeroeth draft. You then take the draft to the requester and let them simmer over it.
What results is an angry email to you (progressively less angry as you house-train the PM) detailing exactly what's wrong with the document. This is the entire point of the exercise. As the requester holds an (un)deliverable in his hands, his mind will process the requirements against the tangible item, thus crystallizing the idea of what the end document actually needs to look like. You, the tech writer, will now get a proper, reasonable request that you can start working on. Result.
It's the writing equivalent of a programmer hacking a workaround for a weird bug in a dependency he has no control over - crude, ugly and annoying; but sometimes there isn't anything else you can do. And this? This works.
1 comment:
Nice, I'll add this to my toolbelt.
Post a Comment