Review by Prescott Williams and Nicki Davis
Successful vendor relationships can make or break large, complex projects, but a vendor who’s proficient and successful in one phase of the project might not be the best choice for another part of the job. These are some key lessons shared by Nicki Davis at the August 19, 2015 San Francisco Chapter meeting.
Nicki recounted the process of a large-scale conversion to the Darwin Information Typing Architecture (DITA), breaking the project down into distinct tasks and phases. For each phase, she rated the vendor/partner who helped. Her company management began to rethink their documentation strategy as the product line grew. Not only did they need to produce more content, they had to support that content on multiple devices. In addition, the typical “content silo” effect resulted in duplication of effort and a lack of standard, consistent, user assistance. Perhaps most painful, the company’s content management system (CMS) was not up to the task of supporting the 10,000 — 40,000 pages required to fully support the growing product line. After evaluation of alternatives, it became apparent that:
1. a DITA-based management system provided the best platform, and
2. they needed help.
The project team broke the task into eight sequential steps for which they needed partners:
- Analyze content
- Train writers in DITA
- Train writers in XML and CMS tools
- Assist with information model (pilot)
- Assist implementation of CMS (pilot)
- Create publication scripts
- Create conversion scripts
- Clean up migrated content
They further determined that four different vendors could best provide assistance, with the tasks grouped as follows:
- Partner 1: Analyze content
- Partner 2: Train writers in DITA; Assist with information model (pilot); Create publication scripts; Create conversion scripts
- Partner 3: Train writers in XML and CMS tools; Assist with implementation of CMS (pilot)
- Partner 4: Clean up migrated content
The work of Partners 1, 3, and 4 was consistently excellent, rating A across the board.
Content analysis by Partner 1 isolated specific problems with existing documentation and developed a set of design goals to address them all. Among other objectives, the project would deliver documentation in one place that supported:
- Governance (clear ownership)
- Review and comment
Training and Pilot Projects
Training programs for the writers, from two separate vendors (Partners 2 and 3), were effective as well. DITA training was a separate curriculum, done by Partner 2. As might be expected, the same vendor (Partner 3) provided CMS training and assisted with the six-month CMS pilot project that immediately followed to reinforce the training. Writers devoted 20% of their time to the new system during the pilot.
Partner 2, in addition to providing DITA training, assisted with the information model and effectively met all requirements. But in the development of publication and conversion scripts, they were less successful.
Markup and Scripts
Preparation of the existing content for export from the original CMS required close examination and analysis. The team marked all topics with the relevant DITA information type (task, concept, or reference) and prepared detailed inventories of shared topics, shared graphics, and “conrefs” in the original material. Conrefs would enable content from one topic to be pulled into another topic in the assembly of user documentation.
Then, Partner 2 was charged with writing scripts to convert the XML from the old CMS to DITA, and in turn publish the desired output from the new CMS. It did not go well.
Script-writing turned out to be much more difficult than anyone – Partner 2 or Nicki and her colleagues – expected. Writing scripts for publishing from DITA, which they expected to be a routine task, turned out to be anything but. The published output had no consistency, with additional line breaks inserted apparently at random. The problem was solved eventually, but not without a great deal of angst. As for the conversion scripts, the team was prepared for a certain amount of manual cleanup because of the need to properly characterize every chunk of information. Nicki referred to this requirement as the need for “intelligent content.” Intelligent content requires semantic markup, and semantic markup requires tagging each chunk as to its purpose.
For example, two steps in a set of instructions may each be followed by a one-sentence paragraph. But one paragraph may give the results of the instruction (“The X dialog box appears.”) while the other gives a screen location (“The ‘Enable’ check box is at the bottom of the dialog box.”) Unless the paragraphs have been marked up properly as “<stepresult>” and “<info>” they will not be converted properly. The team did not expect the conversion script to apply the correct semantic tags to such paragraphs, but did expect the script to mark paragraphs within steps with a single default semantic tag (for example, “<info>”). Paragraphs that were marked with inappropriate semantic tags would need to be identified by writers and re-tagged manually.
Surprisingly, the team was unable to create a script that could recognize the difference between numbered paragraphs and indented non-numbered paragraphs within steps. The script converted every paragraph in the procedure to a numbered step. For example, a procedure with two numbered steps and two non-numbered indented paragraphs would be converted to four numbered steps. In addition to that, text within paragraphs would be duplicated and merged into the preceding paragraph. Needless to say, cleaning up this content required much more work than simple re-tagging. Partner 2 rated A in training and information modeling, but lacked experience with conversion and publishing. Their deliverables, rated D and F, required two additional writer-years of manual cleanup to complete the project.
The writers on the project were challenged by the move from unintelligent to intelligent content, but it gave them a new understanding of their own material. Management learned that vendor expertise in one area doesn’t ensure expertise in another. At the same time, overall the company concluded that even with the difficulties, the efficiencies of outside training and help with content analysis and modeling showed the value of finding partners to assist with large-scale DITA conversions.
About the authors
Nicki Davis, PhD, is a Senior Technical Writer at Complete Genomics, Inc.
Prescott Williams, currently Treasurer of the Sacramento Metro Chapter, wants to grow up to be a “DITA stringer.”