Re: Other kinds of technical writing

[Peter Collins <peter -dot- collins -at- BIGFOOT -dot- COM>]

Ben wrote:
"Or in other words, is expecting programmers to write good technical
documentation the same fallacy as expecting programmers to design good user
interfaces?"
    About twenty years ago I was Head Programmer for a team of about
seventy analysts and programmers. Computer Science degrees were less common
then, and many of the team had liberal arts backgrounds. Worse, many had
science backgrounds. Those who could write well did documentation. We more
or less assigned tasks to those who could do them best. If we had expected
all to do an equal share of the text writing we would have got some
doozies, no doubt at all.
    In my experience programmers with no other background are likely to be
poor writers. But if they have the motivation (and some innate aptitude -
which I think likely for programmers) I believe they can be trained. I was.
    I had been writing all my professional life, but as a programmer I was
not good at it. In struggling to move up from programming, however, I was
dropped in the deep end to prepare a report on which millions of bucks was
riding, and I was lucky enough (though I felt it differently at the time)
to have a manager who was motivated (by the said millions, I suppose) to go
page by page, line by line, word by word through my stuff, debating with me
on structure, presentation, import, implication, reader prior assumptions
and loyalties, political environment - all that sort of stuff. "Nothing to
do with it", I asserted, "the problem is technical, the facts are correctly
stated and they speak for themselves."
    "Not so neither" he told me, "your solution will cost them hundreds of
thousands to apply, so to avoid that expense they will merely not believe
your conclusion, which actually depends upon quite a complex (but valid)
chain of reasoning that they will not sit still long enough to understand.
We can't afford to lose those millions," (I had convinced him, at least),
"so we have to SELL them. I can't rewrite your stuff as a winning
proposal - I would get the facts wrong and anyhow I've got my own job to
do."
    And for the next month under his tutelage I polished every page, line
and word of that text, restructuring, recasting and remotivating. And yes,
the board adopted the Collins Solution and the catastrophe was so averted.
(A true story).
    If they could train me, anyone can learn it, though I admit I have had
nearly twenty years since then to polish up the skills somewhat more.
P
========================================================
Peter Collins, VIVID Management Pty Ltd,
26 Bradleys Head Road, MOSMAN 2088, Australia
+61 2 9968 3308, fax +61 2 9968 3026, mobile +61 (0)18 419 571
Management Consultants and Technical Writers
email: peter -dot- collins -at- bigfoot -dot- com                ICQ#: 10981283
web pages: http://www.angelfire.com/pe/pcollins/
========================================================


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=