December 2021
The Night Before Release
Dawn Stevens, Comtech Services
Dear readers,
I find I’ve set an expectation that my last column each year be a technical writing adaptation of a classic Christmas story. I’ve started to question my sanity, but with rhymezone.com open on one screen, I submit to you this year, my take on the classic poem, A Visit from St. Nicholas, by Clement Clarke Moore.
Have a blessed holiday season!
Dawn
The Night Before Release
‘Twas the night before Release and all through the group
Not a person stopped working, though they’d started to droop.
The content was written by authors with care
and sent to review with a small anxious prayer.
The SMEs were busy with a last minute fix,
Not thinking of its impact to so many topics.
But our leader in wisdom, and we with much doubt,
Had converted to DITA to avoid stressing out.
While last minute changes once caused us to fret
We’d now update in seconds without breaking a sweat.
Away to our keyboards we rapidly went
And opened the specs for the new enhancement.
The language contained in the long overview
Required some time to make our way through.
But soon it became abundantly clear,
That the changes were minor, nothing to fear.
With single sourcing, we’d make the change quick,
And send content to publish with a single mouse click.
Far faster than ever we made our update
Silently praising DITA which increased our work rate.
“Ah, conrefs! Oh, keyrefs! Yay, conditional text!
A keyscope! Branch filters! What will come next?”
To the top of the page! To the top of the map!
Compile the changes without a mishap!
Where Word would have caused a perpetual fight
To get each separate list to number just right,
These changes would look as they should, we knew,
In all our printed formats, and on the web too.
For when moving to DITA we agreed not to stray
From the standards and model we adopted that day.
A subset of elements we have chosen with care
With guidelines that dictate what content goes where.
Our words prudently crafted; our structure consistent;
Output modern and neat; metadata persistent.
Minimalism principles we follow to the letter
And we constantly work to make each release better.
The needs of our users we hold tight in our minds,
To make sure what is needed a search easily finds.
Our content’s always concise and never irrelevant
Our voice friendly and warm, but also intelligent.
Into standalone topics, information is chunked
Ensuring our users are never left stumped.
And should someone have a wrong inclination
Checks are in place to prevent deviation.
Our system’s constrained to keep structure aligned
And Schematron rules our mistakes always find.
We work as a team, help out in a pinch,
And none of our conduct would cause someone to flinch.
Together we worked on our deadline that night
And though we were tired, there was nary a fight.
Completing the update we all sighed in relief
The deadline was met; we’d get no more grief.
We saved all our changes, clicked publish to web,
And waited for output, our strength starting to ebb.
But we heard in our minds, our user’s cry of delight —
“The docs are just what we need and all the content is right!”
About the Author: Dawn Stevens, is CIDM’s Director and President of Comtech Services. She has 30 years of practical experience in virtually every role within a documentation and training department, including project management, instructional design, writing, editing, and multimedia programming.