Semi-colon-oscopy

Stop using semi-colons in your technical documentation. You can stop reading now if you pledge to delete your semi-colons. If you don’t make such a pledge, read the rest of this riveting blog entry.

I used to use semi-colons in my docs a lot. I garnished my paragraphs with them like they were free. Why? Well, there’s a feeling that semi-colons make you looks smart. And, well, they ARE free.

But in the technical world, this type of punctuation is too difficult. Readers don’t know if you’re trying to tie two points together in one sentence or what. It’s like replacing stop signs with  roundabouts in America. Sure, many drivers know how to navigate the circle. But many of us just sit, idling the car with the breaks on, fearing to enter the intersection.

Just keep the stop sign. Everyone knows what to do.

Same with the semi-colon. Stick to simple sentences to make your points or tell your story. Use simpler, shorter sentences that each end with a period. A period is a stop sign that helps your readers navigate through the content. Your translators will love you, and your readers will better understand what the heck you’re trying to say.

Save the flair and style for boring blog posts about punctuation; that was a joke.

Advertisements

About scotmarvin

Scot is a writer for Oracle. He's a slacker and smartass involved in content strategy, content architecture, big data, cloud computing, and other buzzwords related to technical stuff. He loves his family, history books, jazz guitar, and the Minnesota Vikings. Scot is a proud father, so don't make the mistake of asking about his family unless you have four hours to listen to him ramble on about his kids.
This entry was posted in documentation, grammar, writing. Bookmark the permalink.

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 )

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s