Melanie Spiller and Coloratura Consulting
Copyright 2020 Melanie Spiller. All rights reserved.
Seven Simple Things
Melanie Spiller and Coloratura Consulting
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.
1.
Be consistent with yourself. If you start out saying “I did this,” don’t switch to “you do this” or
the reverse, or “we did this.” 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.
2.
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.
3.
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.
4.
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 all the sooner.
5.
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.
6.
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.
7.
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:
a. 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.
b. Look for passive voice and product names, that you’ve minimized the one and been
consistent with the other.
c. 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.”
d. 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.