Seven Simple Things

There are seven simple ways to make your writing look a little more professional without taking courses or investing in editorial services. These things are pretty much common sense, but they bear spelling out.

Be consistent with yourself. If you start out saying “I did this,” don’t switch to “you do this” or the reverse. Either show what you did or tell us how to do it, but don’t waffle between the two. If you start out calling the product a Purple People Plotter, don’t start calling it a Plotter or a plotter or a PPP without telling us that you’re going to change; now call it only by the specified short version, capitalizing the same way every time.
Don’t pile up verbs. See how “the code that would retrieve the data” is less clear than “the code retrieves the data”? In the first sentence, maybe the code will retrieve data and maybe it won’t. In the second version, you take a stand. Brevity often means clarity and multiple verbs generate confusion.
Exercise caution around the verb “to be.” There are lots of good verbs, and you might enjoy giving them some playtime. Your readers will enjoy the variety.
Ask your publisher if there’s a template and use it. Sometimes, the project manager forgets to include a template with your contract, so ask about it. The publishing entity wants styles to be consistent within your document and across other documents, and a template is the best way to make consistency happen. There are usually at least cursory instructions, and you should read them carefully. If there isn’t a template, think about things like heading hierarchies and bullet styles a little before you start. If you don’t have to invent the wheel while you’re writing impeccable prose, you’ll get rolling faster and smoother sooner.
Choose your audience and stick to them. If you are writing to developers, don’t provide definitions for basic terms. You need to provide your definition for controversial terms, of course, but if you’re writing to database developers, for instance, you can just talk about normalization and relationships without defining them. (You can always make reference to suitable coverage, if you have doubts.) If you are writing to beginners or are presenting an entirely new type of product, don’t compare aspects to some advanced situation in a parallel product unless your readers are extremely likely to have used that other tool.
If you didn’t write it, you don’t own it. Sometimes, even if you did write it, you don’t own it. If you have been paid to write something, unless you have legally retained copyright, you don’t own it and can’t quote yourself or copy text without express WRITTEN permission from the copyright owner. And if you didn’t write it, even if it’s a list of features from the company whose product you are writing about and you are being paid by that same company, you need to attribute the source. Your contract probably asks you to warrant that the material you deliver is “original,” and that’s what they mean: YOU wrote it, or properly attributed it, solely for this document.
Read your work at least once before sending it anywhere. If you have to take a break during the writing process, reread what you’ve already done to get the audience, product names, and voice consistent for the next phase of writing. Although a good editor will help you catch those silly switches mid-stream, not everything is edited thoroughly before publication these days, and you could end up sounding like you didn’t read your own work. If you can’t read it, don’t expect anyone else to read it. If you can manage the time, make four passes:
1. Look for linear thinking, that you answered the promise made by the title and subheads, and that you don’t say “there are four things” and then list three or five.
2. Look for passive voice and product names, that you’ve minimized the one and been consistent with the other.
3. Look for audience identification and point of view, so that you don’t leap from saying “I entered the code” to “we entered the code” to “you enter the code” to “enter the code” to “look at the entered code.”
4. Just read it and see how it flows and that you like what you wrote.

If you don’t have time for four passes, do the first one (a). An editor can clean up the rest without having to be technically astute. But don’t turn it in without reading it. Your readers can tell.

Back to Article Index Back to Home