STC New England President Nancy Allison presented technical communication disasters she experienced in her 32-year career, and told attendees how she resolved them, in a monthly program called “Disaster Recovery: Fixing a Documentation Mess,” at the Hilton Garden Inn in Burlington, Mass., on April 20th.
“I love logic, clarity, and good work. I came into technical communication from the communication side, I didn’t come in from the technical side,” said Allison as she began her presentation.
Allison presented five criteria to address a disaster: Perceive the problem, gather the necessary raw materials, identify the signs and wonders that you’re asked to perform, identify who’s asking for a solution, and identify who’s involved in solving the problem. When these five steps are complete, a technical communicator can find an effective solution.
One source of disaster, Allison noted, is companies that treat documentation as an afterthought. Their users expect lousy documentation, she explained, and companies don’t realize its potential to become a powerful tool for users, to dispel their preconceived notions. Consequently, companies hire a contractor, stand over their shoulder to make sure it looks “pretty,” and then publish it.
A technical communicator has a role to help bring different employees together, in addition to educating its users on a product. “We’re informing people in the company how it’s supposed to work, and they’re working from [the documents],” Allison said. Different employees come to technical communicators for help, and technical communicators reciprocate, using their coworkers to find out users’ pain points and information on the product, so they can meet users’ needs better. Allison recommends identifying employees who can be part of a team to solve any documentation problems and unifying them.
If a technical communicator inherits “chopped salad,” information and documents that are not coherent in any meaningful way, he or she should start setting new structure for a new document. Allison noted the technical communicator needs to identify what the appropriate output is, determine the context of use, and then create the table of contents with the team. “That ToC should guide what you pull out of the chopped salad that you’ve pulled together from those other documents,” said Allison.
Clean-up processes are important to bring outdated or old documents into a new format. Allison listed two websites the attendees might find useful. One website offers tools that can clean up Microsoft Word documents and import their contents into Adobe FrameMaker, from Tim Murray at TechKnowledge Corp. here. The other website provides tools to turn badly formatted FrameMaker documents into better formatted ones, at Technical Communication Center here. She expressed that it’s important to decide whether a Word file is worth exporting to FrameMaker or if it’s better to start with a new document.
Allison concluded the presentation with a final tip for the audience: to have fun when fixing disasters. Her last slide featured a wordy passage from a document she inherited. The audience laughed and Allison reiterated how she enjoyed fixing passages like that.
About the Author
Paul A. Duarte is a Documentation Specialist at Canary Systems in New London, New Hampshire. He holds an MA in Professional Writing from the University of Massachusetts Dartmouth. Paul is Vice President of the New England Chapter.