Seven Tips toward Better Writing

What follows are seven tips toward better writing that are informed by my day-job as an acquisition and development editor for Apress. I find authors to write books, and work with those authors on improving their content. Certain problems and mistakes occur with unswerving regularity, and I've chosen seven more or less at random.

StoneTabletsNo.png

Suggestions, Not Rules

Nothing in this post is written on stone tablets. There's an exception for every tip given. You can find at least one person somewhere doing the opposite of what I suggest, and sometimes it will be a publisher doing the opposite.

The tips I give help avoid some of the most common contributors to boring text and incomprehensible prose that I encounter in my work as an acquisition and development editor of how-to books aimed at the technology market. Even when you do the opposite of what I suggest, knowing these tips and the reasoning behind them will improve your writing and keep your readers coming back for more.

Bonus Tip! Give the Editor What She Wants.

Every publisher operates under what is known as a house style. This is a set of rules and guidelines designed to produce uniformity across a line of books (or magazines, or journals), to distinguish the publisher's output from that of their competition, and most importantly to satisfy readers and leave them happy enough to return and buy future content. 

House style includes such things as whether to allow or avoid the majestic plural, whether to provide captions for figures and code listings, how to format those captions, and so forth. Conform! Find out your publisher's preferred style, and deliver on it – unless, that is, you prefer to have an abbreviated writing career. 

Oracle Magazine provides a good example. Soon after I began to write for Oracle Magazine, I learned that my editor preferred a "flat" heading structure. He wanted one level of headings, and not the more complex, nested structure that I was accustomed to using in my books. What did I do? I made sure to write my articles with the flat structure that I knew my editor preferred. In every way possible, I worked to make my editor's job easier, and a delight. 

8a27248v.jpg

Tip #1: Headings Split a Topic

The best way to think about headings is to think of them as splitting a topic. Your main headings in a book chapter split the chapter into major topics. Subheadings split each topic into subtopics. You can't split wood and end up with just one piece. It's the same with content. You can't split a chapter or a section into just one piece. It is wrong by definition to have just one subheading; you should always have at least two.

Following is an example of what not to do. The organization is flawed. Your first clue is the lone subheading. 

Democracies

Blah, blah, blah

Dictatorships

Blah, blah, blah

The solution can be found through recognizing that dictatorship is not typically a subtopic of democracy. You can present the two forms more logically as alternatives under a higher-level topic. For example:

Forms of Government

Blah, blah, blah

Democracies

Blah, blah, blah

Dictatorships

Blah, blah, blah

Now the structure is more sensible. The main topic is forms of government. Two forms are presented as subtopics. The main topic is extensible by adding more subheadings to cover other forms of government such as communism, kingship, and so forth. 

Tip #2: Write in Active Voice

Avoid the use of passive voice, which is the practice of making the object of the verb into the subject of your sentence. Write in passive voice when you want to lull your readers to sleep, or confuse them by leaving them in doubt about who does what. For example, I used to serve as an on-call EMT with the local ambulance service. One day the Sheriff posted the following notice:

Ambulances will be cleaned and restocked after each run.

This was fantastic! What a pain it was to restock after a four-hour loop around the county in the wee hours of the morning. Now I could just go home and crash in bed, and the ambulance would be restocked for me. Right? 

Wrong! What the Sheriff had posted was meant to be an order:

The on-call EMT must clean and restock the ambulance after each run. 

See the difference? Good thing I was a book editor with plenty of experience interpreting passive voice. 

18120550_m.jpg

Tip #3: Introduce Things

Introduce anything that is not body text, and do so before readers encounter that which you are introducing. This means to introduce figures, code examples, tables, and lists before readers encounter them. 

Here's an example that fails at introducing some code:

SQL implements a wide variety of scalar and aggregate functions that are suitable for many purposes. Many are window functions too. 

SELECT AVG (sal) FROM emp;

A reader learning SQL won't know whether he is viewing an example of a scalar function or an aggregate function. Or maybe it's a window function.

Help the reader with an explicit introduction. Say what the code represents, and what it is doing. For example:

SQL implements a wide variety of scalar and aggregate functions that are suitable for many purposes. Many are window functions too.

Following is an example of an aggregate function. The effect is to return the average salary in the firm.

SELECT AVG (sal) FROM emp;

Let body text carry the weight of your writing. Sometimes I imagine to myself what it would be like reading a chapter without being able to see any of the code examples or other non-body-text elements. Good introductions enable me to follow along and get the gist of the discussion without seeing those elements. Aim for writing those good introductions.

Tip #4: Keep the Momentum Forward

Arrange your sentences to be simple and with minimal punctuation. Allow readers to scan and read without pausing to untangle commas and clauses. 

Here's an example of what not to do:

Wanting to move forward, the author made us pause and stumble over that comma. Keeping things interesting, the author wrote like that all the time. Wanting to lose our minds, we persevered in reading the awful prose. With appreciative thanks to our boss, we were finally allowed to cancel the book.

And here is the fix:

The author moved forward without stumbling over the commas. Every word of his content was interesting. There was no time for boredom as we read the entire book in a fit of enthusiastic mania. Our boss was pleased to publish such captivating work.

See how the second paragraph is readable without having to pause and trip over the commas? Aim for that forward momentum in your writing. It may mean that you write some sentences twice, having to see them and circle back around to rewrite one or more times until you've nailed the flow.

Bonus Tip! Don't Stack Headings

Stack your towels. That's fine. But don't stack your headings! By "stack", I mean the placing of one heading directly atop another. Here's an example:

Forms of Government

Democracies

Blah, blah, blah

Dictatorships

Blah, blah, blah

Remember Tip #3 about introducing things? This is a special case of that tip. A section is a "thing". So introduce it! In this case, write a paragraph of two after the main heading to introduce the topic as forms of government. Here's one approach to doing that:

Forms of Government

Many forms of government have been developed through the centuries. Two of the most popular are democracies and dictatorships. Democracies are popular with those who are governed. Dictatorships are popular with those who govern.

Democracies

Blah, blah, blah

Dictatorships

Blah, blah, blah

The canonical form is main heading followed by introduction followed by subtopics. Each subtopic should begin with at least a paragraph of introduction, followed by more content to elaborate and flesh out what is being discussed. 

What follows the main heading should be introduction only. Don't "bury" a topic by covering it in a long section of text following a main heading and before the first subheading. Make sure each subtopic is called out by a subheading. See Example 5 in my article Headings and Subheadings and Why One is the Wrongliest Number.

Tip #5: Identify Your Pronouns

Take care to write clear and explicit antecedents. A good safe harbor is to ensure that each pronoun refers to something explicitly named earlier in the same paragraph. Restate the noun if that's what it takes. 

This next example fails on several fronts:

Democracies

These are thought by many to be the best and most effective of governments. They don’t always agree though. Some prefer a dictator instead, but he may sometimes have a short life due to the nature of “elections” in such a system.

The first pronoun references a noun from the heading. That's a "no no". The Chicago Manual of Style recommends against the heading as antecedent, and most publishers that I'm familiar with heed that recommendation. Following is a clearer version of the content:

Democracies

Democratic forms of government are thought by many to be the best and most effective. People don’t always agree though. Some prefer a dictator instead, but dictators may find they have short lives due to the nature of “elections” in such a system.

Notice how I've phrased the beginning of the paragraph to avoid repeating the word "democracies". One could say: "Democracies are thought by many...". But then the first word of the paragraph repeats the heading, and that's just not elegant. It took only a few seconds thought and some imagination to improve the passage by avoiding the repetition.

There are two other changes: I replaced "they" with "people" to make clear that the passage was referring there to people in general. Then I replaced "he" by "dictators", and tweaked the subsequent phrasing to get proper subject - verb agreement. 

There's more to be said on pronoun failure modes and their solution. See my article Pronoun Panic! if you're interested in a humorous and somewhat more extensive exploration of how to avoid the more common pitfalls.

Tip #6: Choose the Right List

Numbered lists are for steps in a process that you intend to be executed in sequence. For everything else you should write a bulleted list. Reread this paragraph, because it is shocking just how many authors get the heuristic precisely backward.

Here are two lists that do get it backward:

Parts in a Bicycle Drivetrain:

  1. Pedals
  2. Crankset
  3. Bottom-bracket
  4. Chain
  5. Cassette
  6. Freehub

Sequence of Motive Power:

  • Pedals
  • Crankset
  • Bottom-bracket
  • Chain
  • Cassette
  • Freehub

These lists have the same items. The difference lies in the purpose of each list. The first describes a bag of parts, and order is not relevant. The second describes a sequence, and order is at the very heart of the matter. The two lists are correctly presented as follows:

Parts in a Bicycle Drivetrain:

  • Pedals
  • Crankset
  • Bottom-bracket
  • Chain
  • Cassette
  • Freehub

Sequence of Motive Power:

  1. Pedals
  2. Crankset
  3. Bottom-bracket
  4. Chain
  5. Cassette
  6. Freehub

There are also term/definition lists. You can almost look at those as being special cases of bulleted lists. The term is highlighted or in some other way set apart, and you can think of the term as serving the place of the bullet. Read my post on Effective Listing to see some examples of term/definition lists. 

Tip #7: Be up Front

Some authors like to present all the supporting details first. Then at the end of a section they'll conclude by mentioning the main point that they've been building up to, sometimes for several page.

This approach is common in academia, possibly because professors are accustomed to building their students' knowledge in a topic brick-by-brick, so to speak. However, it's a suboptimal approach in business and technical writing. Readers need to know the main thrust of a section in order to have a mental framework upon which to hang the supporting details that you provide after you say what you are planning to tell them. 

Get to the point with your readers, and be up front about what you're planning to say. State the point you plan to make in the very first paragraph of each new section you write. Don't leave readers guessing as to where you are going. State your point first, and then use the rest of the section to elaborate and flesh out your topic. 

Bonus Tip! Simplify and Delete

Some the best self-editing that I do is when I simplify my sentences and delete decorative words and phrasing. Here's a passage I wrote recently that can stand some improvement:

These are just three examples. It is trivial to find more with just a few minutes using a good search engine.

This passage is ok, but it can be improved by cutting it down. The word "just" appears twice, and is repetitive. One or both occurrences of that word can be dispensed with. Here's one attempt at a rewrite that maintains a two-sentence paragraph:

These are three examples. You can find more using a good search engine.

If a two-sentence paragraph is not needed, the passage can be whittled to a single sentence:

These are three examples, and you’ll find more with a good search engine

Don't write Dick and Jane style. There's no need for that. But do try to keep sentences simple and short. Keep them moving forward as in Tip #4. Reduce repetition. Whittle away unneeded words. 

Thanks so much for reading all the way to the bottom. This blog post has roots in a ten-minute presentation I gave at C14 OakTableWorld Las Vegas. It was an honor to have been allowed to present at that event. If you were in the audience, then thank you for attending, and I hope this follow-up post is helpful.