Migrating hardware calibration procedures to DITA

TLDR

To skip straight to my writing sample, see PXIe-XXXX Calibration Template

Goals and results

My goals were to develop a reusable, minimal structure and introduce consistency to a heterogenous doc set that had evolved greatly over time. Another writer has since inherited this doc set, and resued about 90% of my content for her release.

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:

conditions library

  • 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

A previous writer’s introduction to the Adjustment section represented a compromise between our legacy step-by-step coding instructions and a newer, shorter format – but was still quite lengthy:

Before

After

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

Before

Here’s the full DITA template I authored:

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

Conreffed dita topic