Category: Editing

Categories
Editing Tools

The Helpful Machine: 5 Self-Editing Tools to Improve Your Writing

I have always hated spell checkers and am deeply suspicious of automated translation. So I am certainly not pre-conditioned to love automated self-editing tools.

And yet, I’m here to tell you–with enthusiasm!–about a set of tools and techniques that can work wonders for your writing. I have come to use several of these tools on a regular basis myself.

Used the right way, these tools will help you get your message across in a crisper language that is easier to read.

1. Let Hemingway pick it apart

I’ve written about the Hemingway app before. This app got me started using more automated analysis. Hemingway takes you to task for such offenses as:

  • Hard-to-read sentences
  • Too many adverbs
  • Use of the passive voice
  • Difficult words that have simple synonyms

You can use Hemingway directly in the browser. I first wrote this blog post in the Hemingway desktop app, which has some nice perks. You can save and load files, export them to HTML, and turn editing mode on and off. Seeing all that highlighting while typing can be disruptive. This setting lets you think with your fingers first and do the editing later. There’s also support for Markdown.

(For more on how Hemingway works, see my first review of this tool, Your own, personal Hemingway.)

2. Find your Flesch-Kincaid score

The Flesch-Kincaid scale for reading ease is one of the most well-known readability calculations for US English. It’s also the one I choose to look to, although there are many others, mostly because my previous employer used it, and one can only relate to so many scales.

Flesch-Kincaid is more fine-grained than for example the Hemingway readability grade:

  • 90–100: easily understood by an average 11-year-old student
  • 60–70: easily understood by 13- to 15-year-old students
  • 0–30: best understood by university graduates

(Source: Wikipedia)

This makes it easier to track readability improvement of longer documents, which Hemingway in the browser is not so well suited for.

If your writing tool of choice does not have this built in, the easiest workflow is to simply copy/paste the output into readability-score.com.

Oh, and if you’re in documentation, make sure to remove any legal disclaimers you’re stuck with from the text before analyzing it. Their profound lack of readability is probably out of your hands.

3. Use built-in readability tools

Of course, it is easier when testing or analysis is built into the writing tools you already use. This blog uses the Yoast SEO plugin, which includes a readability analysis based in part on the Flesch-Kincaid scale.

If your writing tool of choice (or duty) is Microsoft Word, it can also test your readability for you, but beware:

Depending on your version of Word, not only may Word force you to check your spelling and grammar first, it will warn you that it resets your grammar and spell checkers to do so.

So you may prefer to use an external tool after all. If you want to have a go, try these instructions for setting up readability checks in Word.

4. Check your sentence length

Long sentences are proper readability thieves. If you use Word or readability-score.com, they can both calculate your average sentence length.

The average won’t identify the outliers, of course, for that you need something like Hemingway.

For a good read on sentence length, see this post from gov.uk: Sentence length: why 25 words is our limit.

5. Track and compare your readability

It’s worth noting that you will want to find a readability calculator you like and stick with the same one over time. Different tools use different algorithms, even to calculate scores on the same scale.

When you have ensured comparable results, start comparing! Accumulate your own readability statistics. I’ve used a simple spreadsheet. You can track and compare revisions of the same document over time, or compare different documents to ensure a consistent readability level.

Good trends, bad trends, consistency, it will all be easy to see and act on as required.

The blog post Write Better: Online Readability Testing Tools Compared shows how different results tools produce for the same piece of text.

The best editors and proofreaders remain human

Of course, these tools and tricks won’t re-structure your entire document or tell you that your blog post is at least twice the length it needs to be. Or that your jokes just aren’t funny. For that, you need an editor, a proofreader, or at least an honest friend or colleague.

I do find that having self-editing tools to help me spot the low-level issues makes it easier to spend time on those other factors, though.

And here’s a bonus “tool”: Time. If you have to be your own editor, give yourself a little time and distance from your text before re-reading and polishing if at all possible.

Do you have any experience with self-editing tools and techniques? Share your tips and hard-earned lessons in the comments!

Categories
Editing T-shirts Technical Communications

Link Roundup: APIs and Fine Manuals

Still wrestling with my next post on error messages. Meanwhile, I’m sharing some excellent links on technical communications I’ve happened upon lately.

Categories
Editing Writing

Making A List? Check It (At Least) Twice!

List-making tips summarized: Use the right kind of list, avoid redundancy, and be consistent

List writing can be a great way to make content accessible and scannable and give readers an overview. Lists are everywhere, and for good reason.

A well-written list can be a quick read, but when making a list, taking some time to properly consider the format and syntax will pay off in clarity and helpfulness for your readers.

Below, I have gathered some advice for writers and editors dealing with lists, based on my own writing and editing experience. If you have other tips or pitfalls on your mind, please share them in the comments!

Use The Right Kind Of List

It’s easy to think that usage conventions for list types are exactly the kind of thing only writers would care about. If you think that way–I have myself on occasion–then consider this progress screenshot from a WordPress backup plugin that I recently installed:

Screenshot of a message saying DO NOT DO ANY OF THE FOLLOWING and goes on to list in numbered sequence 3 actions not to perform while the installation is ongoing. When making a list, try not to confuse people more than necessary.

Without reading this multiple times, would you feel certain that you were actually not supposed to do anything mentioned in this numbered list? The introduction says one thing, but the choice of list type is communicating something different entirely.

Use an ordered list if you are describing any of the following:

  • a procedure to follow
  • a sequence of events to observe
  • a clearly prioritized order

Some may also prefer alphabetical ordered lists for options where only one may be selected (“Do one of the following: a. b. c. d.”).

If the list is not a sequence, an unordered bullet list is the most common option. However, long bullet lists are not particularly easy to read. For lists that are long and/or include a lot of information in each list item, these two other options are worth considering:

  • description lists (definition lists pre-HTML5) for glossaries, metadata listings, and similar. These tend to be styled in a manner that make them a lot more scannable than bullet lists. See Mozilla Developer Network for a good description and examples.
  • tables. I know, tables are not actually lists, nor do they have the Twitter or Pinterest appeal of a Top 5 list, but for reference-style material, a table provides much better findability and overview than a bullet list.

I like lists, I’m controlling, I like order. I’m difficult on every level. (Sandra Bullock)

Avoid Redundancy

List items that start identically, or semi-identically, reduce scannability. Keep in mind that tables of contents are also lists. If you have a table of content that is generated based on your headings, considering each heading a list item is useful.

To ensure list items remain scannable, you can:

  • front load each list item by starting with important keywords that set it apart from other list items rather than something generic , such as “You will need to …” or “For simplicity and ease of use, we have …”.
  • move repetitive phrases outside of the list itself. For example, instead of starting each list item with “how to”, make “how to” part of the introductory phrase that comes before the list.
  • drop any words and expressions that don’t add to the meaning. In most cases, list items don’t need to be complete sentences.

As a bonus, if your writing will be translated, you’ll save money by avoiding redundancy.

Every morning I get up and look through the Forbes list of the richest people in America. If I’m not there, I go to work. (Robert Orben)

Be Consistent

In a list, each item should have a similar syntax. This is a pet peeve that probably annoys me as a writer more than most readers, but I have seen plenty of bullet lists that would be confusing for any kind of reader.

Before unleashing a bullet list on the world, read through it starting with the introductory phrase and check that all list items:

  • start in a similar fashion to the others and read as a grammatically correct continuation of the introductory phrase. If the introduction says: “This chapter will tell you how to:”, you cannot have list items starting with “making” or “configuration”.
  • share the same grammatical subject or state their subject clearly. Otherwise you may easily conflate, for example, something done automatically by software with something  users must do themselves, or something the software vendor can do for you upon request. In my experience, this problem is not uncommon in lists of features and software specifications.
  • use similar syntax and punctuation. Mixing questions with statements in the same list will usually not read well. Whether or not to end each list item with a full stop is a style/preference issue. It is also painfully hard to remember and follow up on in a consistent manner.

We like lists because we don’t want to die. (Umberto Eco)