Migrating Calibration Procedures to DITA

Task

My assignment was to migrate 8 calibration procedures from FrameMaker to DITA. These procedures are mainly used by an internal audience to develop automated calibration applications.

Goals

 My goals were to develop a reusable, minimal structure and introduce consistency to a heterogenous doc set that had evolved greatly over time.

Outcomes and Lessons Learned

Another writer has since inherited this doc set, and has been able to reuse about 90% of my content for her current release. Now another writer is interested in adapting my approach for a separate product group, so I'm sure I'll learn more about how adaptable my content is.

When you look at the source behind a typical topic I structured, you can see it's entirely reused:



 In mentoring my successor, I've learned several DITA reuse lessons:

• Attempting to implement a "semicontrolled" vocabulary through conrefs (for example, conreffing table titles, math variables, and figure titles) is probably overdoing it in most cases
• Successful sharing strategies need to be flexible, and can allow for mixed approaches. For example, we're using a combination of standard conrefs and push topics for test conditions and cautions, and that seems to work:
• Conreffing generic instructions (while using keydefs for numbers, equations, and figures) seems to work reasonably well, though our library topic for steps is getting a little out of hand and I worry future writers will have difficulty finding the steps they need. I've tried to break the library topic  up by subject area to help with this issue, and if I had to do it again, I probably wouldn't author such granular keydefs.

Before and after comparisons

Here are some example of how I rewrote to cut wordiness and chunk content:

Before (adjustment intro)

A previous writer's lengthy introduction to the Adjustment section represented a compromise between our legacy step-by-step coding instructions and a newer, shorter format:

After (adjustment intro)

I split up the Adjustment introduction into reusable chunks, cut a lot of content, and included coding instructions only for select portions: 

Before (load regulation)

A previous writer's procedure varied in wording for similar steps and occasionally called out numbers that could have been better be placed in tables (in the interest of reusing structured content):

After (load regulation)

 I rewrote in the interest of generic, reusable steps.  I standardized and conreffed all steps, and added conditional steps so that we had flexibility with keydeffing our tables: