Sunday, June 25, 2017

Using Commas - Part Two

In this continuation from the previous lesson, we will dig deeper into using commas in technical writing.

Avoiding the comma splice 

A "comma splice" is the incorrect usage of a comma to separate two independent clauses. (Reminder: an independent clause has both a subject and a verb.) For example:

The server has started, you can log in.

The first clause has the subject "The server" and the compound verb "has started". The second clause has the subject "you" and the compound verb "can log in". Therefore, they are both independent clauses.

When there are two independent clauses, you can separate them in the following ways:
  • Use a period if they stand alone as separate ideas: The server has started. Log in using your credentials.
  • Use a comma and a conjunction if they are connected ideas: The server has started, and you can now log in.
  • Use a semicolon if they are closely-related ideas: The server has started; you can log in.
(You could also use dashes, but we won't cover that until the next lesson.)

Semicolons can lead to long and somewhat ambiguous sentences, so we tend to avoid semicolons in technical writing. It's better to create two separate sentences with a period, or use a comma and a conjunction that clearly shows how the ideas are connected. For example, consider this sentence:

The server is starting; you can log in now.

Does this mean you can log in because the server is starting or in spite of the fact that it's still starting up? A comma and conjunction make the two different meanings clearer:

The server is starting, so you can log in now.
The server is starting, but you can log in now.

Using commas with adverbs

An adverb modifies a verb, an adjective, or another adverb. They often end in "-ly", which makes them easier to spot. For example:

He ran swiftly. 
("swiftly" is the adverb modifying the verb "ran")

The really fast connection made surfing the web a lot more fun. 
("really" is the adverb modifying the adjective "fast", which is modifying the noun "connection")

He ran incredibly swiftly. 
("incredibly" is the adverb modifying the adverb "swiftly", which modifies the verb "ran")

As you can see, you do not use commas between adverbs and the words they modify. The exception is when you repeat an adverb for emphasis, such as: 

The really, really fast connection made surfing the web a lot more fun.

But don't do this in technical writing, please!

Put the adverb as close to the word it modifies as possible. For example, "Swiftly he ran" is fine in poetry, but it sounds awkward in technical writing. Worse, moving the adverb away from the word it's modifying can also create confusion in more complex sentences. An exception is when you put it at the end of an imperative (command) sentence to add emphasis:

Return to the front desk immediately.

You could also write "Immediately return to the front desk", but it sounds more like a general instruction and less like an urgent command. 

This brings us to sentence adverbs, which usually do appear at the beginning of the sentence and are followed by a comma. A sentence adverb modifies the sentence as a whole instead of a specific word. It is useful for expressing an opinion. For example:

Incidentally, your father dropped by earlier.
Sadly, the ball was canceled.

When I write these sentences, I'm expressing the opinion that the information I'm giving you about your father stopping by is an incidental aside, and I'm expressing sorrow that the ball was canceled. You can also put sentence adverbs in the middle or end of the sentence to put less emphasis on them:

Your father, incidentally, dropped by earlier.
The ball was canceled, sadly.

Notice that wherever you put the sentence adverb, it's always separated from the rest of the sentence by commas.

Using commas with imperatives

An imperative is a command, such as "Type your password at the prompt." The implied subject of this sentence is "You", and the verb is "type", so it is an independent clause. Even the one-word sentence "Go!" is an independent clause, because the subject ("You") is implied.

When you have two imperatives whose ideas are closely related, even though they are independent clauses, you don't need a comma between them. For example:

Type your password and press Enter.
Change the Foo property to BAR and click OK.

If the second clause is long, or if it is more of a separate step, you can use a comma. To avoid confusion, I often insert the word "then" when I'm using a comma and conjunction between imperatives. For example:

Change the Foo property to BAR, and then select the action type. 


You might be wondering why we have all these rules for commas. In technical writing, our goal is to get the information as quickly and accurately as possible into the reader's brain, and using commas correctly helps a lot. Just remember that even if a sentence is punctuated correctly, you must rewrite it if it violates the hiccup rule

In the next lesson, we will cover hyphens and dashes. 

Additional resources

Saturday, June 17, 2017

Using Commas - Part One

(This post is part of a series on writing fundamentals aimed primarily at technical writers, but creative writers should find it useful as well. For more context, see The Hiccup Rule.)

Commas can be beastly. In this post, I'll cover some of the most common scenarios where people run into trouble with commas.

Don't use a comma to separate the subject and predicate

The subject of the sentence describes who or what the sentence is about. The predicate describes the action of the subject. For example, in the sentence "Sandra went to the park," "Sandra" is the subject, and "went to the park" is the predicate. 

Sometimes, I see writers put a comma between the subject and predicate, which is incorrect. For example:

Sandra went to the park.
The writers and editors are learning to use commas.

Sandra, went to the park. 
The writers and editors, are learning to use commas. 

Addressing someone specific

You do put a comma after the subject if you are addressing the person directly, such as in an email:

Sandra, have fun at the park today! 

As another example, both of these sentences are correct and mean two different things because of the comma:

Writers, take every opportunity to learn about commas. (I'm addressing the writers directly and am telling them to go learn about commas.)
Writers take every opportunity to learn about commas. (I'm making an observation that writers in general are driven to learn about commas.)

Separating a dependent clause from an independent clause

Let's get into something a bit more complex. Clauses have a subject and a verb. An independent clause forms a complete thought and can stand on its own as a sentence:

Sandra went to the park.

A dependent clause (also called a subordinate clause) provides more information about the independent clause and cannot stand on its own as a sentence. Consider this dependent clause:

When Sandra went to the park

When she went to the park...what? What happened? Because it starts with the dependent word "When", it's not a complete thought on its own and needs an independent clause to finish the thought:

When Sandra went to the park, a pack of wild dogs appeared. 

Now we have the dependent clause (When Sandra went to the park) followed by the independent clause (she saw a pack of wild dogs), and the thought is complete. 

Notice that there is a comma between the two clauses. Here comes the tricky part: when the dependent clause comes first, use a comma, but when the independent clause comes first, don't use a comma. (English is ridiculous sometimes.)

Using our previous example, the dependent clause is first, so there's a comma. If we reverse the clauses, though, you do not use a comma:

A pack of wild dogs appeared when Sandra went to the park

Why do we need the comma when the dependent clause is first? Well, consider this sentence:

Before configuring the server, users must download the correct version of the JDK.

If you didn't have the comma, a reader would see this at the beginning of the sentence:

Before configuring the server users

Can you see how readers might think this sentence is talking about server users? If so, readers will become confused when they get to "must download" and will pause and reread the sentence. And that breaks the hiccup rule, which is a big no-no in technical writing. 

Using that vs. which

This is an important topic that happens to fall within the discussion of commas, so let's tackle it!

Figuring out when to use "that" or "which" before a clause can cause writers to tear their hair out. Here's how it works: if the information is essential to understanding which thing you're talking about, use "that". For example, if you have two cars, and you want to tell me about the car in the garage, not the car in the driveway, you would write:

The car that is in the garage is broken down. 

This is an example of a restrictive clause, also called an essential clause, because it's required in order for the reader to know which car you're talking about. Use "that" to introduce restrictive clauses.

However, if you only have one car, and you are simply mentioning its location as an aside, you would write:

The car, which is in the garage, is broken down. 

This is an example of a nonrestrictive or non-essential clause. The information is not required for the reader's understanding and is just additional information.

Notice that when you use "that", you do not use any commas, whereas when you use "which", you surround the phrase with commas. Look at what happens if I omit the commas in the second example:

The car which is in the garage is broken down. 

Now, the reader has no way of knowing whether "which is in the garage" is essential (there are multiple cars, and I'm talking about the one in the garage) or non-essential (there's only one car, and it happens to be in the garage). So whenever you use "which" to introduce a non-essential clause, be sure to surround the clause with commas.

If you're talking about a person instead of a thing, use "who" instead of "that" or "which", and use commas to indicate whether it's essential or non-essential information. For example:

The agent who read my book called me yesterday.  (I sent my book to multiple agents, but only one read it, and she's the one who called me). 
The agent, who read my book, called me yesterday. (I sent my book to only one agent, and she called me yesterday. As an aside, she actually read my book!)

You can see a nice blog post entirely devoted to restrictive and non-restrictive clauses over at the Grammerly Blog

Using serial commas

People are damn passionate about this topic, so I'm about to alienate half my readers. Into the fray!

The serial comma, also called the Oxford comma, appears after the second-to-last (penultimate) item in a series. For example:

The server receives the request, sends the response, and logs the activity.

That comma before "and" is the serial comma. Because it can make a difference in meaning, we always use it in technical writing, and I use it in my creative writing as well. However, AP Style dictates that you do not use a comma after the penultimate item, so you'll notice its absence in news articles, marketing content, etc. So if a marketing piece were to write the same sentence, they'd usually write:

The server receives the request, sends the response and logs the activity.

This might not seem like a big deal until you consider more complex sentences or a series where the word can mean two different things. For example:

Every day after work, he drinks a beer, eats a burger and fries an egg.

Did you pause for just a moment after "fries", because you were grouping "burger and fries" in your mind and thought "fries" was referring to french fries? There goes the hiccup rule! With a serial comma, there's zero confusion:

Every day after work, he drinks a beer, eats a burger, and fries an egg.

Let's look at another example:

In his speech, he thanked his parents, Elvis and Madonna.

This makes it sound like Elvis and Madonna are his parents. With a serial comma, though, it all becomes clear:

In his speech, he thanked his parents, Elvis, and Madonna.

To see a really hilarious (and not quite safe for work) illustration that drives this point home, check out this Verbicide post. Read the comments if you want to see how worked up people get over this topic. 


Commas are very important for communicating clearly. When used correctly, they break up complex sentences, set off non-essential information, and help avoid the dreaded hiccup rule. 

In the next post, Using Commas - Part Two, I'll talk about more pitfalls with commas. But for now, let's take a pause. 

Additional resources

Sunday, June 11, 2017

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.

Saturday, October 29, 2011

It's Time to Write!

Summer is over, and I have finally concluded my annual creativity hibernation and am starting to write again. Hibernation? you ask. Doesn't that happen in winter? Not to me. Every summer, I find my creativity wanes to the point where I can barely write anything at all. Not even blog posts. The only explanation I can offer is that my muse likes to go on summer holidays, but she tends to return all fresh and glowing in October. I know better than to ask her where she's been, but without missing a beat, she returns every autumn and assumes her familiar place next to my ear, takes a soft breath, and starts whispering.

So here I am blogging again after the summer drought, and what better topic to discuss than the perfect way to launch yourself back into your craft: NaNoWriMo!

For the uninitiated, November is National Novel Writing Month, or NaNoWriMo. It's when everyone from first-time dreamers to seasoned authors pull together to wrangle their muses in a sort of crazed, Sadie Hawkins sort of fashion so they can Write Their Novel. The goal is to write 50,000 words in 30 days. Mind you, they don't have to be good fact, the idea is that you don't focus on quality at all and just write. At the end of the month, you upload your document, the web site validates the word count, and you celebrate.

I like the idea of NaNoWriMo for so many reasons. One, I am a big fan of the idea of Just Write. Two, I think community and structure are a huge help, even though I've always done without either one. Three, if more people can at least get introduced to the addiction of writing, we might help some wonderful new writers to begin their careers.

Sound intriguing? Let's do it! I have 30,000 words on Madness already (book four of The Soterians series), but my goal is to finish the first draft, which I'm targeting at 80,000, so I have another 50,000 to go anyway.

What do you say? You in?

Sunday, June 5, 2011

Balancing Light and Dark

Ever since this unfortunate Wall Street Journal article appeared, Twitter has exploded with countless posts using the #yasaves hash tag describing how young-adult (YA) books have been a lifeline for people. How those suffering from self-injury, eating disorders, bullying, and abuse of all kinds have found they have a voice through these books, which speak for them even if they can't speak for themselves. As I read these posts, I came across this picture, which to me says it all: 

Dear @wsj, #yasaves on Twitpic

The interesting thing is that some look at this picture and think it means that the books are promoting all the crap on the wall. My interpretation is this:

Kids know where they've started; books help them see where they might go.

It's a concept very much like the It Gets Better project, which was started to help gay teens see that high school is about as bad as it gets, and if you just hang on and don't kill yourself, you're probably in for a much better time. The people contributing videos to the It Gets Better project are sharing their own stories of how they were rejected, bullied, misunderstood, teased, and generally made to feel less than human at a time when the most important thing in the world is to fit in. Are those videos teaching bullies new ways to torture their gay classmates? Of course not. The videos act as a lighthouse, giving teens the hope they need to get through a horribly difficult time.

The irony of high school, you see, is that so often we're told by well-meaning adults that it's the best time of your life. That you don't have a care in the world, you just get to play with your friends and go to parties and have a great time, and just wait until you have to start working full-time. For a kid who is struggling with the pressures of schoolwork and fitting in and self-loathing and isn't getting invited to those supposedly wonderful parties, what kind of message is that? Adults think that by trying to paint a rosy picture of the teen's life, they'll somehow make it more rosy, and that by acknowledging that the ages of 13 through 18 are usually the very worst time of a person's life, they're somehow making it more miserable.

But kids aren't stupid. I knew what I was experiencing in high school, and nobody was going to convince me that my suffering wasn't real. Luckily, I was able to listen past the rhetoric and had an inkling of the freedom that being an adult would bring me. And to this day, even when I'm tearing my hair out with stress at my job or slogging through my taxes, I am so grateful that at least I make my own money and don't have to remind my employer every week that they're supposed to pay me. That I have a home with nobody telling me about what is acceptable under "their" roof. That my friends love me even when I'm fat, don't sneer at my clothes, and don't turn their back on me because of the sexual choices I made the night before. That I don't have to ask for permission and money every time I want to buy a pair of jeans, or depend on the whim of an adult to decide whether I get to have a social life that weekend. That as an adult, I get to be part of this democratic society I was forced to learn so much about in high school, when my reality was much more along the lines of totalitarian rule.

Kids know where they come from. They know that the pain they're experiencing is real, and what they need more than anything else is to hear that a) they're not the only one experiencing this, and b) there's hope of a future beyond their current misery, whether that misery consists of not getting into the "in" crowd or being abused by the people who are supposed to be protecting you. This is why there is a whole range of books in YA fiction--to say that they're all violent and perverse is ridiculous.

If you're still unconvinced that teens need to read about the dark side of life, ask yourself this: when is the last time you read a book about a perfect, happy workplace? Or a marriage with no arguments? Did bosses become pointy-haired because they started reading Dilbert? Did spouses start cheating when they read books about the misery that it causes? Of course not. The reason these books are popular is because like it or not, life is full of good and bad, light and dark, and we need to talk about all of it. Ironically, I think a lot of adult fiction is way too obsessed with the dark side--I often say that the best way to have a New York Times best seller is to make sure your plot includes raping children and killing pets. But there's a big difference between gratuitous use of these subjects and exploring the interplay of the dark and light side of life and all the shades of grey in between. We need to talk about our experiences, and we need to read about the similar experiences of others. It's what connects us, and it's what gives us hope.

So instead of bashing young-adult fiction across the board, and bemoaning the fact that Barnes & Noble didn't do a good enough job of picking books for you and your children, do your own research. Read the YA blogs with your kids to find out what sounds appealing and appropriate. (To expand your options, I recommend reading blogs that review self-published books as well as those traditionally published.) And then, here's the revolutionary part: after you've bought the books, read them. Pass them back and forth with your teens, and then discuss the stories. Find out what they thought of it (seek to listen first; don't jump into preaching mode!) and how it made them feel. Was there anything they could relate to? Anything that brought up their own fears and anxieties? You'll be astonished by how much kids will share within this context, because they feel that if the character in the story could talk about it, then maybe they can, too. And then you can share your own experiences from when you were a teen (watch their eyes get wide as they realize you existed before they were born).

But a word of caution: when you tell your stories, be sure to share a balance of the light and the dark. Because just like with good fiction, you need both to be truly authentic. 

Saturday, May 21, 2011

Taking Your Story to the End of the World

Amidst all the madness about the world supposedly ending today, I came across this amazing video, which shows artist Zack Smithey painting while Messiaen's Quartet for the End of Time is performed in the background. What struck me most was how he paints such a beautiful piece of art, but along the way he adds so much paint that it runs and covers other parts, and in the end, he allows the entire thing to be obliterated. I found myself getting very anxious watching this, wanting him to preserve the lines that were already there, worrying when he sprayed paint across the parts that were already "done," not wanting him to ruin it and to safeguard it forever.

You can see where I'm going with this.

I realized as I watched this video that I'm way too protective of my characters and my story lines. I lead them through danger, but I get a nagging sense that I'm still holding their hands. I'm pretty good at cutting out whole parts and revising dialog and such, but once I've written a story line, it's very hard for me to go back and take another path instead. And I simply cannot imagine throwing the whole thing out and starting over.

And yet, the only way you can get the richness of a great story, or the tension that makes us root for your characters, is to put them in real discomfort and peril, not to keep them safe, and to go back to the parts that are already "done" and layer on those details that really bring your story to life. You must be both the creator and the destroyer. You need to be willing to take your story and your characters to the end of the world...and if necessary, obliterate everything.

In short, you must become detached from your work, even as you create it with painstaking love and care. You must detach yourself from what you want from your characters, where you want the story to go, how you want your story to be received by readers, and how successful you hope it will become. Only then, when you write as fearlessly as this painter created and destroyed his work, can you be free to write the best story you can possibly write.

It's a tall order, but at the very least, we should have it in the back of our minds as our goal. As an exercise, I'm going to spend some time today pretending that today really is the end of the world, and then I'll see what I write. I suspect it's going to make a difference in how my characters behave and where I take them. If you try this exercise, please comment and let me know how it worked out for you. (If you're still here, of course.)

Wednesday, April 27, 2011


If you're a writer, chances are you have struggled through moments of such doubt that you have almost completely lost hope. It's essentially a crisis of faith, in yourself or your ideas or the publishing industry. Those moments where you feel like you don't have it in you to stare at the blank page another day, to rewrite that scene one more time, or to send another query letter. Moments where you feel like there's simply no point to it anymore.

The cure to those moments, I've found, is action. If you're stuck with a blank page, take action and give yourself permission to fill the page with nonsense just to get the words flowing. If you're struggling with a scene, ask yourself whether you're trying to make too much of a point or are caught in dialogue that's going nowhere. Instead, write an action scene to get things moving again. Likewise, if you feel like you'll never be published, polish your query again and send it to another agent anyway, and do some research into indie publishers or self-publishing. Knowing that you have options is very important for keeping your hope alive.

The amazing thing is that there's almost a magical alchemical reaction that occurs with action. The moment you take action, motivation begins to seep through your veins. It causes your characters to wake up and do and say interesting things again. And the nonsense words slowly make way for the pearls that were stuck behind a dam of hopelessness. Because when action works its magic, you start to have hope again, which causes your faith in yourself and the world to return, which leads to the motivation to take action again. It's a wonderful upward spiral.

So when you're feeling like you just can't motivate yourself to take action, the cure, ironically enough, is to take action. Don't pour a drink and mope. Don't call a friend and complain. Close your web browser and email program, turn off the TV and the phone, and just act. Because even if the action you take isn't the right outcome in and of itself, it will kick off the motivation cycle that will lead to what you truly want.

Go ahead. Give it a try. You have nothing to lose but hopelessness.