Getting Modular

by Rick Lorenz

The Eastern Ontario Chapter of the STC met at Macie's Best Western on the snowy evening of November 21, 2000. Following light refreshments, Visnja Beg presented Designing Object Oriented or Modular Documentation. She based her presentation on an article she wrote for the July/August 2000 issue of Intercom. After the presentation, attendees began a lively (though well-moderated) discussion of their experiences and ideas.

Visnja explained that with modular documentation, modules/chunks of writing can be reused. The philosophy is, "Write once. Use anywhere."

This has a number of advantages. The information is easier to update, and (with the right tools) every document that uses the module can be updated automatically. Because modules are reused, the documentation set is more consistent. Solution documents, which are custom made for specific applications, are easily compiled from existing modules.

Modular documentation has four elements:

1. Standard writing style - This is achieved by following a style guide, and through adherence to process.

2. Procedural modules - Modular documentation doesn't use conceptual topics. Conceptual information is included within the procedures. Procedural modules are easy to add and remove.

3. Encapsulated information - Modules must be independent and provide value on their own. Procedural modules (with required conceptual information) are naturally encapsulated.

4. Appropriate tools - Required tools include a database to organize modules, a text editor, and a tool to compile modules into output. In this context, a module is ASCII text marked up with tags. Each tag contains meta data that identifies the content of the associated text. Therefore the tag indicates more than the format of the text or how it's placed in the document structure...but the DTD will use the tag to make these decisions when compiling output.

To succeed with modular documentation, you must first do a lot of planning. During the discussion, attendees told stories about planning taking months longer than normal. However projects were completed on time because the writing went so quickly. As usual, a good starting point is putting yourself in the user's position. What does the user want to do? Employ audience analysis, task analysis, task modelling, and use cases to figure this out...you can even try talking to some users.

Note that it's easiest to do modular documentation if starting from scratch, and if the product is object oriented. It's well suited for software with a core program and plug-in modules purchased separately. By definition, it lends itself to single sourcing.

The discussion revealed some other advantages with modular documentation. The final output is shorter because there is less repetition. However the planning process reveals holes in existing documentation, which are then filled in with useful content. Overall review time is less because each module is reviewed once for all applications. The module is also honed over time, improving the quality of the documentation set. The workflow between writers (and SMEs too) gets better because each module is owned by one writer. Modules are written in ASCII with ASCII tags, so the source data in legacy documents will be readable for years (even a person can read ASCII). An interesting technique is to build a profile of the user with a wizard-based user interface. The program can then retrieve, structure and output modules to match the user profile.

Follow this link to read or download Visnja's Intercom article:
http://www.stc.org/intercom/PDFs/2000/200007-08_22-25.pdf

Visnja's PowerPoint slides are also available: docDesignPres.ppt

---

A report on the panel discussion:
"What makes an award-winning document?"

by Rick Lorenz

(See also: Rick's Report on the AGM.)

On April 12, the STC and ITE held a joint meeting at RMOC for a panel discussion on what makes an award-winning document. For $8.00, I got a light dinner, and the opportunity to hear expert opinions. Doreen deMunnik moderated the panel, which included Gordon Brown, Bob Stanley, David Wegenast and Paul Leroux.

Gordon Brown managed this year's print competition, and won a merit award in the 97-98 online help competition. He started as a print journalist, worked at Corel, and is now a team leader and documentation specialist at Nortel Networks. Gordon discussed the attributes a writer must have to produce quality documentation:

Bob Stanley has been involved with the STC for many years. He ran Stimulus for several years and managed the 98-99 competition. He has served as a judge and has won a number of awards, serving and winning locally and at the international level. Bob started as a reporter in England, and has worked for most of the major companies in Ottawa.

Bob talked about judging documentation. Judges are experienced writers who tend to volunteer each year. They use a comprehensive set of guidelines formalized by the STC. They are each assigned about five entries, and have three weeks to review them. At the end of the review period, the judges meet in teams of three to score the entries. Judges don't have time to read an entire entry, depending on its size. For example, their conclusions may be based on 10% of a 300 page manual. They pay close attention to detail, checking things like index entries, pagination and spelling.

David Wegenast has been on the ITE executive for many years, and is currently president. He has judged for a number of years and has won multiple awards, both locally and internationally. He worked for a magazine, later graduated from the Technical Writing program at Algonquin College, and is now manager of technical publications at Autodesk Canada.

David stressed consistent, but also creative adherence to the STC guidelines. Documents must be usable, and must encourage use of the product by generating a sense of excitement. Things like colour and attention to layout show concern for the user.

Paul Leroux has won multiple awards for QNX over the past decade, including many this year. In fact he needed a box to carry all the certificates home from the awards ceremony.

Paul began by questioning the discussion topic; should the emphasis be on winning awards? More importantly, we must concern ourselves with our users. Fortunately, the criteria for winning awards matches the user's needs. Paul then told us that documents need a human touch. They must portray that other people are involved, have shared their struggles with the product, and are on their side. This doesn't necessarily mean a folksy style, but rather reassurance at stumbling blocks that they are on track.

Once the presentation was complete, audience members identified themselves and asked questions. Here are some highlights.

Dr. Ralph Callistro (a prominent STC member) was on hand, wondering how documents can be judged without access to the product and its users. The panelists indicated that judges assume the information is technically accurate. However experience has honed their instincts, and they can tell whether the information is complete, internally consistent, and meets the user's needs. All the elements of good technical writing must be present to win. Therefore you can enter the competition, not for an award, but to get feedback and insight on a document you're vaguely unsatisfied with.

Audience members questioned the validity of the STC guidelines. They don't mention "concise", or "lends itself to translation". Aren't these characteristics important? The panelists explained that these attributes are indirectly included, because a document must have a "clear presentation of required information". Paul said that being too concise isn't always appropriate. Sometimes it's better to add text to maintain the user's comfort level. For example, if the system takes a long time to complete a step, the user may think the computer is locked up. The user will be more relaxed if told to wait for a few minutes.

An audience member asked what sort of manuals tend to win. A manual about a familiar consumer product has better chances than a reference manual for abstract high-tech software. However reference documentation has won awards.

Are you interested in the guidelines that judges use in STC competitions? Do you want to know what makes a good document? Go to www.stc.org, and follow the Competitions link. From the Competitions page, follow the 1999-2000 Judging Evaluation Forms link. From the Judging Evaluation Forms page, you can download PDF files with guidelines for the Online, Art and Publication competitions.