To err is human…

I started my week by editing error messages.  Error messages for an installation program.  Over 100 error messages.  I learned a few lessons from this edit.

1. Editing 10 error messages consistently and accurately is much easier than editing 100 error messages consistently and accurately. I found that I started out great, but by the end I was taking shortcuts or not being as diligent to ask all the questions about the context of the messages to be able to provide the most useful information, while also trying to make those sentences grammatically correct and adhering to all our guidelines and standards for messages. I think editing consistently across larger sets of information is one of the biggest challenges that technical editors face. Next time, I will break up an edit, and take a break between editing the chunks of messages.
2. Because there are often many unknowns in the realm of error messages, and because I must apply a variety of style guidelines, grammar rules, and content standards, I am prone to making grammatical errors in my edits!  You wrestle with verb tenses, passive voice, and technical jargon as you try to untangle and revise a message.  Let’s look at an example.

   Where we started:
   “An error during the creation of the configuration directory prevented the installation program from generating the file.”
   (I have removed a few product-specific details in order to focus on the grammar issue, and in order to be able to share it.)

   My first edit attempt (which created a dangling modifier!):
   “Because an error occurred when creating the configuration directory, the installation program could not generate the file.”
   (The error did not create the configuration directory.  I was merely trying to get rid of “during the creation of”, but didn’t pause and re-read my edited message like I should have.)

   We went through a couple of other iterations, but we collaboratively wrote this message:
   “Because an error occurred when the installation program was creating the configuration directory, the file was not generated.”

   I was quite embarrassed to create a grammatical error in my suggested edits, but my writer was quite empathetic to my plight.  Editing messages is just plain hard to do, and making grammatical errors amidst so many unknowns is easy to do.

I believe it was Alexander Pope who said, “To err is human; to forgive, divine.” But, this morning as I finish my cup of tea as I write this, I am reminded of the other play on this quote: “To err is human; to really foul things up requires a computer.” A rather appropriate quote for a blog post about editing error messages, don’t you think?

Happy editing everyone!