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.