KeyLogic Blog: Tips From Our Technical Writers

In all my years of writing and reviewing communications products I have found that there is no punctuation mark more confusing to most writers than the semicolon. Conventional wisdom seems to be to avoid its use altogether in favor of breaking up long clauses or phrases into shorter sentences—and that would be a mistake. The semicolon is uniquely qualified for performing a number of very specific and important syntactical tasks and omitting it altogether limits the ways a writer can create—and a reader can perceive—written language.

User guides explain how to do something, whether it is how to download a software program, perform a business task, or assemble a desk. They should be simple and easy to follow, and should never, ever be vague enough to cause a public disturbance worthy of a police investigation.

Many people have no idea what the Oxford comma is, but likely have opinions on whether or not it should be used. What exactly is the Oxford comma? It is punctuation mark so trendy that a hipster band (Vampire Weekend) wrote a song about it. The Oxford comma also has a staggering 32,000+ likes on Facebook.

From Mad Men to Nashville to House of Cards, portrayals of writers abound in the media. Technical writers, however, are rarely the subject of TV shows—or movies or books, for that matter—and it can be hard to imagine what exactly it is they do. So, how do technical writers differ from writers in general?

Many people assume that editors spend their days hunting down typos and eradicating comma splices. But in fact, our responsibilities are much broader than that. When you send us a document, we typically give it three levels of editing: content editing, copyediting, and proofreading.

Working for a government contractor, we are accustomed to using many abbreviations in our daily communications. Unfortunately, some of them have so infiltrated our vocabularies that their original meanings were forgotten long ago, leading to the ubiquitous: “what does < insert abbreviation > stand for?”

Good question. Dictionary.com defines a copy edit as one that’s done "for publication, esp. for punctuation, spelling, grammatical structure, style, etc.”. If you send your document to a copy editor, you can expect to get a ‘clean’ document back—he or she will make sure the commas are all in the right places, nothing is misspelled, and will fix all those pesky typos or misused forms of your and you’re. A copy editor knows when to capitalize titles, and the best of them will make minor changes to your text to help it flow better.