Needle in a Haystack

I just finished what was one of the longest days of my career so-far at Bentley. And everything that was bad about today was entirely my own damn fault and could have been easily avoided if I’d just been a bit more careful.

In addition to pushing some publishing updates to our documentation CCMS last night, I also decided to roll out my new Troubleshooting DITA specialization. It’s based on the specialization that is expected to ship with the DITA 1.3 specification sometime next year, but uses our specialized domains and works with DITA 1.2. That’s mostly tech comm nerd talk for I decided to give the writers a new template geared toward writing troubleshooting tips.

Unfortunately, even after thoroughly testing it on our development server, I managed to mess things up by added a comment to a couple of DTD catalog files after all of my testing but before making a backup of the production environment. That is, I didn’t really have a backup of the functioning production server. Rather, I had a copy of some files I had just made a minor edit to, one of which included a critical error. An error I ended up spending all day today trying to locate and correct.

Eventually, I realized I had left a single “>” character in an XML comment copied over to a text catalog file (the text catalogs aren’t XML and have the angle brackets stripped out – something I will now do with XSL instead of manually!). This one particular catalog file is used to locate the DTDs for our desktop DITA editor and no one was able to check out or create new content in our CCMS as a result of that one errant character. It took me about ten hours to figure this out (well, maybe nine hours of panic attack and one hour of actual clear-headed work). Thus leaving half-a-dozen writers with no good way to edit some of their files today as well as me feeling like a jerk for not being more cautious.

I just wrapped up my fixes —both tested thoroughly in their final form and put into place after backups of the working production environment were made. I’m going to check in with my colleagues in India shortly to ensure they can now edit and create content once again.

Lesson learned; and I am humbled.