Scriptorium Publishing

content strategy for technical communication

Streamlining authoring for military standard documents

Customer: U.S. government national laboratory

Our client creates documents that must follow United States military specifications (“mil-spec”). The client’s templates did not fully support the mil-spec standard, so writers did a large amount of custom formatting in the files. We created a template that fully automates and supports mil-spec formatting requirements. We then developed a workflow that produces Extensible Markup Language (XML) output to support the client’s future needs.

Writers spent a significant amount of time creating custom formatting to match the military specifications. Provided that the printed document looked correct, any approach, no matter how inefficient or unmaintainable, was permitted. Editors reviewed documents page by page to ensure that headers and footers were presented and aligned correctly. They also checked numbering in headings and in paragraphs; errors were common because the numbers were inserted manually. The authoring environment was very inefficient.

Our client also wanted to produce XML from documents to permit document interchange and to enable an easier transition to content management in the future.

Fix template problems

The template provided to authors did not take advantage of FrameMaker’s useful automation features. We built an unstructured FrameMaker template that accommodated all of the complex mil-spec formatting requirements, documented it, and trained the authors on how to use it.

Implement structured authoring

Working closely with our client’s technical experts, we built a content model for the client’s information. Once the content model was built, reviewed, and approved, we built a structured authoring environment from this model.

We modified the formatting template built in the first phase of this project, and added an element definition document (EDD) that described the structure permitted in our client’s documents. We also built the components required to export XML from FrameMaker.

Develop conversion process

Our client chose a phased implementation. As a result, two content migrations were required—from the legacy content to the new formatting template and from there to the structured template.

We developed, tested, and delivered a conversion process for both migrations. We developed extensive scripts to automate conversion as much as possible.

Create new deliverable formats

Our client delivers information mostly as paper or PDF. HTML, however, is becoming more important. We created an Extensible Stylesheet Language (XSL) transformation that produces HTML from the exported XML. The client could then create HTML from the FrameMaker source files. Our client chose XSL transformation over commercial FrameMaker-to-HTML converters for several reasons:

  • XSL is an open standard, and free processors are available. No additional software licensing cost was incurred.
  • If, in the future, our client chooses to move to XML-based authoring, the XSL transformation will still be usable.

Provide knowledge transfer

The final piece of the project is perhaps the most important one. We wrote documentation for all of the system components—formatting template, EDD, structured application, XSL, and so on. We are in the process of training our client’s technical experts on the entire system so that they can take over maintenance. This summer, we will train the authors on how to create information in the new system. The course materials include a customized workbook with exercise files based on the client’s structure. After the initial training provided by Scriptorium, the client can use the workbook to introduce new employees to the publishing system.

Summary

When we began this project, authors were focused on creating information that matched the military standard on paper. The underlying formatting was considered unimportant. By moving to a template that actually supports the needed formatting and then to a structured authoring environment that enforces the presence of required elements (such as captions on figures), our client is improving the quality of their documents and reducing the effort required to create correct formatting. Our client is now ready to create XML as needed, can exchange information with other organizations, and is ready to move into content management. After knowledge transfer is complete, the client will have the ability to support the system in-house.

Leave a Reply

Required fields are marked *.