Liz Marlow, Yoel Strimling, and Oz Malach of Comverse explained how they took a “legacy” document, revised it, and evaluated its role with the customer. All of their steps were shown, along with a few examples for us to see how it was done. All three had their individual roles in this rebirth of the document.

Liz began the talk by giving on overview of the revision process. The first step was to evaluate the document. It was inspected to determine if it was clearly written, if it was easy to find what was needed, if it was relevant to the audience, and to determine if it was too specific for certain customers. The overall quality of the document: how it was written and its visual interface was determined. To plan the transition of this document, research in how it was used and how to make it more applicable was determined.

The next decision was how to revise the document. A modular methodology was adopted to change the documentation from its linear form. Chunking was very important to make the document more readable. Also critical was labeling and linking: clear headings for the reader to recognize information included under that heading and linking to help the reader navigate through the document, or as Liz described it “mapping and glue.”

Implementing the changes needed was next, rewriting and restructuring did not necessary change the tools. These included:

•·      Separate descriptive and task information, such as using gerunds to introduce the procedure and including sections “What you need” and “How”

•·      Make topic labels clear

•·      Make the look and feel of the document and graphics more attractive and effective: chunking

•·      Write in clear grammatical style

•·      Add meaningful links to related information

What was done was to modularize the content, update the look and feel with better use of white space, templates, and icons, and make sure the design was for the users in mind with PDF and HTML options as well.

Yoel continued with describing his role as the editor. He said that he is probably the only person to read a document linearly, from start to finish. His job is much more than mere checking the grammar. He needs to look at usability, clarity, consistency, and accuracy. The audience, which he described as attention deficient and irritable, must be able to read and understand the material at the first reading. As far as the modularity aspects, he checks that they are grouped into meaningful topics that are appropriately labeled and linked intelligently. He also must keep the information task oriented, short, and to the point. The editor has a chance to solve problems early, or as he put it, “A bit of prevention is worth a megabyte of cure.” The editor must also ensure consistency. This is especially important when there are a number of writers contributing to a body of documentation, or one specific document. Once distracted with how the document is written, the reader will then look at the style and not the content. Yoel ended with the importance of a clearly defined style guide that helps the writers keep writing.

But clarity and consistency is not everything, especially if the document is not usable. Here is where the talk was continued by Oz Malach. Oz described his function as a “Documentation Engineer.” His job is to ensure relevancy and accuracy:

•·      Bridge the knowledge gap between R & D and the Technical Writer

•·      Indicate any gaps in content

•·      Assist in locating relevant source information

•·      Guide and train writers in understanding source information

•·      Know the needs of the audience: nature of the work onsite

•·      Collect all the pieces that make the whole document: make sure no piece is left out and it all fits together in an organized fashion

•·      Make sure the document is complete

•·      Make sure the document is technically correct

Oz, who previously worked at Comverse in its Customer Support, Training, and Development departments, is well acquainted with the needs of the audience, as well as keeping the technical aspects of the documentation accurate. Having an expert on the audience, as well as the technical aspects to be documented, the documentation engineer can keep the writers comfortable with what they are writing.

Where does this lead the Comverse group? They have multiple products, multiple technologies, and multiple customers. How can they use what they have done with the documentation program described here and yet aim for customized content? There must be a unified view of how to combine these into a consistent methodology that can deal with all the aspects. They call it Customized Management Sources:

•·      Modular documentation, with improved clarity, accuracy and relevance

•·      Writing based on templates for consistency

•·      Reviewed by both editor and documentation engineer

•·      Aimed for customized content produced from single sourced content which spans multiple products, yet supports various customer needs.

The PowerPoint presentation of this seminar can be viewed at http://www.stc-israel.org.il/ChapterInfo/2007_Convention/2007IC_presentations.htm