Needle in a Haystack

I just fin­ished what was one of the longest days of my career so-far at Bent­ley. And every­thing that was bad about today was entire­ly my own damn fault and could have been eas­i­ly avoid­ed if I’d just been a bit more careful.

In addi­tion to push­ing some pub­lish­ing updates to our doc­u­men­ta­tion CCMS last night, I also decid­ed to roll out my new Trou­bleshoot­ing DITA spe­cial­iza­tion. It’s based on the spe­cial­iza­tion that is expect­ed to ship with the DITA 1.3 spec­i­fi­ca­tion some­time next year, but uses our spe­cial­ized domains and works with DITA 1.2. That’s most­ly tech comm nerd talk for I decid­ed to give the writ­ers a new tem­plate geared toward writ­ing trou­bleshoot­ing tips.

Unfor­tu­nate­ly, even after thor­ough­ly test­ing it on our devel­op­ment serv­er, I man­aged to mess things up by added a com­ment to a cou­ple of DTD cat­a­log files after all of my test­ing but before mak­ing a back­up of the pro­duc­tion envi­ron­ment. That is, I did­n’t real­ly have a back­up of the func­tion­ing pro­duc­tion serv­er. Rather, I had a copy of some files I had just made a minor edit to, one of which includ­ed a crit­i­cal error. An error I end­ed up spend­ing all day today try­ing to locate and correct.

Even­tu­al­ly, I real­ized I had left a sin­gle “>” char­ac­ter in an XML com­ment copied over to a text cat­a­log file (the text cat­a­logs aren’t XML and have the angle brack­ets stripped out — some­thing I will now do with XSL instead of man­u­al­ly!). This one par­tic­u­lar cat­a­log file is used to locate the DTDs for our desk­top DITA edi­tor and no one was able to check out or cre­ate new con­tent in our CCMS as a result of that one errant char­ac­ter. It took me about ten hours to fig­ure this out (well, maybe nine hours of pan­ic attack and one hour of actu­al clear-head­ed work). Thus leav­ing half-a-dozen writ­ers with no good way to edit some of their files today as well as me feel­ing like a jerk for not being more cautious.

I just wrapped up my fix­es —both test­ed thor­ough­ly in their final form and put into place after back­ups of the work­ing pro­duc­tion envi­ron­ment were made. I’m going to check in with my col­leagues in India short­ly to ensure they can now edit and cre­ate con­tent once again.

Les­son learned; and I am humbled.

By Jason Coleman

Structural engineer and technical content manager Bentley Systems by day. Geeky father and husband all the rest of time.

Leave a comment

Your email address will not be published. Required fields are marked *