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
- 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.
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
- 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.
- Look for passive voice and product names, that you’ve minimized the one and been consistent with
- 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.”
- 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.