TechWell Writing Tips and Style Guidelines

TechWell, Better Software magazine, and Software Quality Engineering's other publications follow the usage guidelines described in the Chicago Manual of Style. On this page, we address some of the most frequent usage questions from our authors as well as the areas where we diverge from the Chicago Manual of Style. We will update it regularly, so that it may be a helpful source of information for our writers.

If you have a specific question that isn't covered here, please post it to the TechWell Writers' Forum.

American English

While our products reach readers all over the world, we distribute them in English and use American English spelling for the sake of consistency. If English isn't your first language and you feel uncomfortable with its usage, consider co-writing with someone who writes in English or having that person review a draft of your article before submitting it for publication.

If English is your first language, but you typically use the British English spelling of words—e.g., "humour" instead of "humor"—we apologize for removing your u's. If it helps, please feel free to continue pronouncing the letter z as "zed" rather than "zee."

Pronouns, Number, and Gender

Traditionally, authors have used the singular masculine pronoun to represent a nonspecific person who could be male or female—e.g., "Each of the developers offered his opinion." Over time, authors have adopted alternative forms like "his or her." That's fine if used sparingly, but too many "his or hers" can really clutter up an article. Alternating pronoun gender also can lead to confusion. And, though its usage goes back many centuries, forcing a "singular they"—e.g., "Every tester has their own workstation"—is arguably gramatically incorrect and can be incredibly jarring to a reader.

There is no perfect solution. For the sake of clarity and consistency, we use the gender of an article's primary author for these generic pronouns.

Punctuation and Quotation Marks

The Chicago Manual of Style, as with many other style guides, calls for periods and commas to go inside the quotation mark at all times, semicolons to go outside the quotation mark at all times, and exclamation marks and question marks to go either inside or outside the quotation mark, depending on whether the mark is related to the content within the quotation mark or the sentence as a whole.

Examples:

• Period: I enjoyed Naomi's blog post "'Start Late' and Other Tips for Miserable Meetings."
• Comma: "The conference exceeded my expectations," she said.
• Semicolon: Recent articles on the topic include the following: Jonathan Kohl's "Software Project Estimation"; Mary Gorman and Ellen Gottesdiener's "Agile Planning and Analysis: Synergizing to Deliver Value," which appeared in May; and Lee Copeland's "The Third Age of Requirements."
• Exclamation mark related to content outside the quotation marks: I was shocked by the so-called "penalty"!
• Exclamation mark related to content inside the quotation marks: He screamed from the office down the hall, "I quit!"
• Question mark related to content outside the quotation marks: Why do you suppose she told us to "pick up the pace"?
• Question mark related to content inside the quotation marks: He asked the doctor, "When my hand heals, will I be able to play the piano?"

Serial Comma

We use the serial comma after the second-to-last item in a list of three or more items, often just before the word "and."

Example: The organization includes programmers, testers, and managers.

Some style guides and many newspapers elect not to use the serial comma until a sentence requires it for clarity. In the example above, omitting the serial comma doesn't necessarily affect the meaning of the sentence: "The organization includes programmers, testers and managers."

However, the serial comma does add clarity to certain sentences. If you attend the circus and bump into a couple of friends, you might write, "Under the big top, I saw clowns, Bertrand and Friedrich." Without the serial comma, a reader might take this sentence to mean that Bertrand and Friedrich are the clowns you saw at the circus. If, on the other hand, you saw clowns and Bertrand and Friedrich at the circus, you could convey this clearly by using a serial comma.

As with many elements of grammar, the serial comma is a style choice rather than a perfect solution. If you write, "I received emails from Plato, the editor-in-chief, and Jean-Paul," you may have received emails from two people (editor-in-chief Plato and Jean-Paul) or three people (Plato and the editor-in-chief and Jean-Paul).

For the sake of consistency, we use the serial comma and address exceptions when necessary. The most important thing is to be clear, so the reader doesn't lose focus on what you're saying in order to decipher how you're saying it.

Other Tips

Lists
Numbered and unnumbered lists provide a simple method of displaying bytes of information and are acceptable in moderation. However, please keep in mind that an overabundance of bullet points in print or on a web page can be distracting to a reader.

Figures
We welcome the inclusion of graphic elements with your article. Photos can draw a reader into an experience story. Charts and diagrams can illustrate concepts that may be difficult to describe with words alone. If you would like to use an image created by someone else, please let us know in advance so we can obtain reuse permission and give proper attribution.