The Hiccup Rule

I've been MIA from this blog for over six years. During this time, I finished the Soterians series with the fourth and final book, Madness, at the very end of 2015. It was so hard to say good-bye to my characters, and I still miss them. I've had some other ideas for stories I want to write, but I'm not quite ready to go down that rabbit hole again and lose myself in an alternate reality.

Meanwhile, since January of 2013 I've been very busy building and leading the Technical Content group at WSO2, where we are responsible for creating the documentation and training for incredibly cool software products. I love writing, whether it's novels or technical documentation, and everyone on my team shares this passion. Several of them have asked me to review the basics of technical writing with them, including grammar and punctuation. A few months ago I started putting together lessons, and I quickly realized these lessons might make good blog posts.

So my next several posts will be devoted to some thorny topics that make people tear their hair out, starting off with commas. There are dozens of sites devoted to grammar, punctuation, and writing, and my lessons borrow heavily from many excellent resources. Still, if you're a militant grammarian, or a follower of AP style, you're likely going to have some choice words for me in the comments. These lessons are geared specifically toward technical writing for software, and we use the Microsoft Manual of Style as our foundation, so I'm not interested in hearing about why the Oxford comma is unnecessary (it's not, for reasons I will make clear).

Keep in mind that the goal of technical writing, unlike academic or creative writing, is to get the information into the reader's head as quickly as possible with no voice, persuasion, or distracting language. Users often come to the documentation only after they're already frustrated, so the last thing they want is to have to wade through grammatically perfect but confusing or flowery sentences.

Which brings me to the most important rule of all: the hiccup rule*. That is, if you stop mid-sentence and realize you are a bit lost and need to re-read the sentence, it has caused you a mental "hiccup" and should be rewritten. It doesn't matter if the sentence is grammatically correct: if it fails the hiccup rule, it is wrong. This is something one of my early mentors taught me, and I think it's the most valuable rule you can remember.

There are times when I'm reading a novel and find myself so distracted by beautiful prose or clever wording that I have to go back and re-read the sentence or paragraph. I often enjoy this experience, but it also pulls me out of the story and makes me think about the author and about writing, so I tend to follow the hiccup rule with my creative writing as well. It's completely up to you to decide what your goal is as a writer. For some, playing with language is paramount. For others, it's all about the story.

Whatever your goal may be, it's helpful to know the rules so that you can break them with discretion. I hope the lessons that follow will be informative and give you the confidence to do just that—without hiccups.

* If you found this post because you have real hiccups, drinking water upside-down always works for me.