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.

Making a list? Check it (at least) twice!

Making a list is 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!

Tips for making a list summarized: Use the right kind of list, avoid redundancy, and be consistent

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)

Your own, personal Hemingway

Ernest Hemingway famously lamented writers that hadn’t learned “how to say no to a typewriter”. The Elements of Style, one of my favorite books on writing, advises that we “Omit needless words”. While that may be easy to agree with, it is quite hard to live by, especially for those with limited or no access to a skilled editor. Self-editing is difficult!

The other day on Twitter I came across a link to the web app Hemingway, and I was immediately smitten.

What it does

You can type or paste your text into the web interface, and Hemingway calls out:

  • complex sentences
  • adverbs
  • uses of the passive voice
  • fancy words and phrases that you can omit or replace with simpler synonyms

Hemingway uses an easy-to-grasp color legend to signal where the issues are. Accessibility-wise, this heavy reliance on color coding is of course bad news for colorblind users.

Hemingway screenshot

Test runs

I’ve run the tool on a few different texts, including:

  • An IPCC fact sheet. Hemingway gave it a “10 Good” and minimal highlighting, which I think is an impressive result given the subject matter.
  • The Wikipedia entry on Client-server architecture. Hemingway said “14 OK”, with some very complex sentences and a few uses of the passive voice.
  • A random piece of Buffy fanfiction. “5 Good”, although containing a rather high number of adverbs.
  • This blog post, which I kept re-testing until I was happy with the result. The first draft got “11 OK”, with a few complex sentences and some fancy words that were better replaced or omitted. You can see the result of the final run in the screenshot above.

I have tried with a few different texts and so far failed to get Hemingway to say anything but “OK” or “Good”. I even ran the analysis on a patent document where 74 out of 250 sentences were “very hard to read” and there were 86 uses of the passive voice. Hemingway still found this to be “14 OK”.

The verdict

I dislike spell checkers and the grammar and syntax checking in word processors, and I have rarely bothered to use readability analyzers on my text. This might just be the tool that convinces me to embrace automated readability checking as a supplement to the editing and reviewing I otherwise may have access to. I gather that I like this tool because I feel like we’re on the same team. Clean, helpful, simple writing is what we want, and to that end, the tool has a clean, helpful, simple interface.

The app has some obvious shortcomings. The most obvious is that the analysis is not able to call out overall verbosity. A human (and hemingwayesque) editor would immediately strike down on long and repetitive text. I also find the individual highlighting a lot more useful than the readability score, which is often far too kind. If you manage to find a text that gets a terrible score, do let me know in the comments!

I will keep trying out this tool with my writing both for work and for this blog. The creators are trying to find out whether there is interest in a $5 desktop version that would be able to save and load files. I have signed up to receive notification when and if the desktop version releases.

This app may not turn any of us into Hemingway, but for self editing, it is probably the most helpful tool I have seen so far.

(The New Yorker has of course subjected Hemingway to the Hemingway app test.)

© 2017 Techy Writer

Theme by Anders NorenUp ↑