Writer urges ‘non-techie’ approach

Making writers technical, rather than teaching techies to write, is the easiest path to good technical documentation, says visiting Boston-based technical writer John Garison. 'Someone who knows very little will ask questions and then explain the subject better, putting it into context".

It's easier to teach a writer to be technical than to teach a “techie” to write, says John Garison, principal technical writer for Boston-based Integrated Development Enterprise.

People who understand technology tend to assume everyone else does, says Garison, “whereas someone who knows very little will ask questions and then explain the subject better, putting it into context”.

Garison will be in New Zealand next month to speak at the New Zealand Technical Writers Association conference. He is looking forward to the event as conferences provide a good opportunity for writers to catch up on current trends, as they “live in Internet time — everything moves seven to 10 times faster in this job than most”.

Writers are currently in a difficult position, because the IT industry is in a state of flux. “There are all these different standards being developed — by Sun, by Microsoft — and we have to try to keep up with it all.”

Garison believes over the next 15 years things will change even more and he foresees three major trends: XML will have a huge impact on development; computers will “de-computerise” as fridges and other household appliances get more intelligent; and software programmes will become more “dynamic, individualised and built on the fly”.

Technical writing for manuals provides Garison with a great challenge. “I get to be Sherlock Holmes, following clues to sort out how things work, and then I can be Watson too, explaining it in simple language.”

That language has to be tailored to its audience, though — a guide to software for experienced users “doesn’t need to say ‘press enter’ every time, while other guides need that level”.

Without a skilled writer, technical documentation “is usually only useful for propping your monitor up at eye height”.

Join the newsletter!


Sign up to gain exclusive access to email subscriptions, event invitations, competitions, giveaways, and much more.

Membership is free, and your security and privacy remain protected. View our privacy policy before signing up.

Error: Please check your email address.
Show Comments