Murphy’s Law for Software

February 14, 2010

It happened to me again

On the day of a deadline, a critical software error prevented me from delivering my work on time.  With panic surging, blood pressure rising, and rational thoughts growing ever harder to form, it occurred to me (much, much later, I admit) that I need a better process for managing Murphy’s Law, particularly as it applies to software tools.

Murphy’s Law – anything that can go wrong, will go wrong, and usually, when there is no time left in the cycle to address it.

First Problem: Thursday was a deadline date for us on the CA ARCserve Backup project. All documentation had to be handed over to the localization team so they could start translation. At this point in our process, the doc set is published and posted every day because we make changes to it every day.

The Admin Guide in this doc set is huge – nearly 900 pages. I spent Thursday afternoon changing all the topics written to support a new feature in this release, adding new screen shots and icons that represent devices. By the end of the day, I’d modified about a dozen topics in our AuthorIT SQL database.  We notified the localization team they could begin when ready and then we published all the changes for the day.

That’s when AuthorIT said “Uh uh, no way, can’t do that, I quit” and refused to publish the Admin Guide. Given the size of this doc, it takes about twenty minutes to publish to PDF format. This particular error occurred at 99% complete and all the application told us was that a VB script error occurred.  There’s no one to call for Support at 5:30 at night, the localization team was just handed bad content, and I’m sitting there unable to think straight, save for the occasionally muttered, “holy crap”.

After I got my panic attack in check, I was able to think more clearly. We knew the guide published successfully the day before, so we could narrow down the search to topics changed Thursday. We pulled one topic out of the book at a time, tried to publish, and eventually pinpointed the problem topic. This process took over an hour, since publishing is a slow process for a book of this size.

The diagnosis: AuthorIT does not like graphics inside tables. I removed the table, used a layout tool to organize the graphics manually, dropped the resulting single composite image into the topic and that’s when the next error occurred.

Second Problem: Out of Memory.

I haven’t been able to figure out why this happens. RAM is maxed out on this computer, I’m not running tons of other applications, nor does the error always happen. I’d just spent over 2 hours publishing and suddenly, this time, poof – Out of Memory. I tried killing background processes, but it didn’t help. The only thing that does help is to kill AuthorIT and restart it – which I had to do two or three times during the troubleshooting exercise, above. *excuses self to step away and rant*

Experts at the AuthorIT user forums want to blame this on Word, even though I’ve reported the error happens when I publish to HTML, too.  There are ongoing issues with our AuthorIT 5.2 implementation that we hope are solved when we upgrade to 5.3 at the end of the month, so I must live with the frustration a bit longer. I find myself fondly reminiscing the days of Selectric typewriters, where the only thing I had to worry about was running out of Correcto-tape and ribbons.

We FINALLY managed to get the Admin Guide to successfully publish to Word and then PDF, but not until Friday morning.  (We left the office at nearly 8 PM Thursday night. I never did eat dinner that night.) Of course, it was too late to provide the fixed content to the localization team. They’ll either have to redo the work they’ve done, or somehow replace the corrupt topic manually in ten languages.

What’s the alternative?

Since experience and hindsight are required to design an effective contingency plan, I now keep a careful record of what changes I make to AuthorIT topics on a daily basis, and test publication often. Luckily, I have access to other machines from which I can run the lengthy publishing process without monopolizing my main computer.

Software applications are tools on which we heavily rely so when they crash, we can’t work. If you have war stories to share, I’d love to hear your methods for working through software issues.



  1. Unfortunately, AuthorIT is just not good software.

    • I loved the 4.x release. Never had an issue with it until we upgraded to 5.

  2. Hi Patty,

    I’m sorry to see that you had some trouble with your publishing recently and I’d like to offer some assistance.

    I can’t say I’ve ever seen a problem that was related to the use of a file object within a table, but it’s quite possible that the VB error occurred due to something related to either the image or the table and once one of the elements was modified the error went away. Did you happen to keep a record of the exact wording of the error message? I’d be interested in doing some further research to see if I can isolate the specific cause.

    The out of memory message is a whole different ball game and it’s hard to get into detail without knowing the specifics. I’ve seen a small number of cases logged about similar messages when publishing to Word, but none for HTML based publishing. In most cases it came down to a problem with either the Word template or the Word installation itself. The installations were corrected by running Word’s Detect and Repair option, and the templates by using Words Open and Repair option (in the Open menu). There were also two reports that were resolved by restarting the computers involved indicating that there was a resource issue on those specific machines.

    I’d quite like to help get to the bottom of this message for your HTML publishing as that seems quite unusual. With this in mind I’d like to invite you to log a support case with us via http://my.author-it.com , when logging the case please include information on your computers specifications (CPU, RAM, OS etc…) and if possible please provide a copy of a book known to result in this message to XML and send that along to us following the instructions provided in the email you’ll receive when the case is logged.

    If Author-it is indeed at fault here we can get to the bottom of it faster by using data known to cause the behaviour and we can then get down to resolving it for you.

    I look forward to working with you on this behaviour.


    Author-it Support

    • Thank you, Julie. I’ll do that later this week. We’re still managing the fallout from the problems on Thursday.

  3. BATTLE!

    I’ve never used AuthorIT. Typically I’ve used WebWorks or RoboHelp when I’ve had to do my own generation work. At bigger companies, they have Desktop Publishing teams and writers just write, but at most places you do this kind of work yourself. Whenever the publication system I use (whatever it might be) fails, then it’s time for battle. The war is on. Now I have to hack into it and figure out what was wrong – same as you. Same as all of us have to do. Every publication system is full of vaguely understood bits and pieces. Yes, we know conceptually what they’re doing there. We get that this “thing” is a big engine that pulls in content from various places and puts it together according to predefined rules that we’ve dumped in at various times. The end result, when it works, is due to our efforts at describing how the formatting should be applied, and how the layout should be… well… laid out! But when it DOESN’T work, then it’s time to figure those things out.

    And that means battle. Battle against technology. What do all these bits and pieces REALLY mean, and why aren’t they working together? Trial and error. Take it apart and generate again to see what happens. Research via a million blogs and forums to see what other people have said. Google specific elements to identify their possible purpose and potential failures. Check the creator of the software and see if you’ve missed an update. Are all the versions correct? Is there a conflict with some other sofware? Are the custom scripts you threw together during the last panic and freak-out session still doing what they were designed to do? What’s the weakest link in this system anyway. Hey, it’s probably me. Am I even USING this thing correctly? User error – maybe. Can’t rule it out until you rule it out.

    Speaking of which, an update came out just the other day, and I need to install it. I should probably generate afterward too, or I’ll be sorry when crunch time hits and nothing works.

  4. I have this image of medieval armor and weapons as I read your post. That is EXACTLY how I felt last week.

    In this case, I am leaning toward user error. I don’t think AuthorIT likes graphics embedded in tables – indeed, there is no style tag in our template for such. Once I removed the table, all was well across the land.

  5. Hi Patty,

    I just wanted to clear up what seems to be a small misunderstanding in regards to the VB error and the use of images in tables.

    Author-it fully supports the use of images in tables.

    VB errors are Microsoft Visual Basic errors and indicate a problem with a Word Macro used in the Word template. It’s possible that the macro cannot process something about the table when it includes an image.


    Author-it Support

  6. Thank you, Julie. I believe problem #1 was pilot error (me) and problem #2? Not sure yet. But I greatly appreciate AIT’s willingness to help me solve it.
    Amended 2/22/10: Upgraded Author-IT to 5.3. I’ve published a dozen Word to PDF docs and another dozen to HTML. No errors! *flips cartwheels*

  7. i just know this page, nice blog you have,
    i will visit this web more often and read about your post,
    i like ur topic specially about
    Murphy’s Law for Software


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: