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:
- 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:
After
I split up the Adjustment introduction into reusable chunks, cut a lot of content, and included coding instructions only for select portions:
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:
