Author: Jorunn

Categories
Editing Tools

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! Enter the Hemingway app.

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

What Hemingway 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.

Putting Hemingway To The Test

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.

The Hemingway app may not turn any of us into an author the level of its namesake. For self editing, however, 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.)

Update: I wrote some more about the Hemingway desktop app here: The Helpful Machine: 5 Self-Editing Tools to Improve Your Writing

Categories
Technical Communications Writing

Kill Your Darling Tech Analogies (Almost Nothing In Life Is Like A Car)

Old car matching a building in Grünerløkka, Oslo.

Over the years, I have come to fear and loathe most uses of metaphor, simile, and analogy in technology discourse. Interesting, helpful analogies are the exception rather than the norm.

What makes a bad analogy?

The main problems as I see it, are that the images people use tend to be:

  • Unoriginal and predictable. 9 times out of 10, it involves a car or traffic. (Seriously, have you tried a Google search for * is like a car?)
  • Hard to understand. How many people understand, in technical detail, how a car works?
  • Far-fetched at best, faltering and completely unnecessary at worst. Because not that many things in life are like a car.

Explaining an unknown with an unknown

Far-fetched is your smallest problem if you are able to get the first two right; be at least somewhat original and make it understandable to your audience.

Understanding is where you can’t afford to fall short, because for an analogy to be successful, at least one side needs to be well known to your audience, and both of them need to be familiar to you. You can explain something your audience doesn’t know by comparing it to something they know. Or you can give them new perspectives on something they do know by comparing it to something that might be new to them.

However, way way way too often, I see tech analogies that try to explain an unknown with an unknown. An audience that is already struggling to grasp a technology concept, is asked to wrap their brains around another concept that is somehow related to the first, in ways that shall only be fully revealed once they properly understand both concepts.

I’m not going to claim that it is impossible to pull such a dual explanation off. But it is very hard and requires the speaker or writer to realize that they must explain both sides of their analogy for it to work.

Ignoring cultural context is a related pitfall. For example, some traffic rules vary by country and continent, as do knowledge of and interest in sports. On this subject, I recommend Espen Andersen’s blog post on Pitfalls for the US speaker in Scandinavia.

Loving your analogies too much

The real problem with doing away with poor metaphors and analogies, though, is that as their makers, we tend to fall in love with them. I don’t use them a lot myself, but when I do, I can find myself struggling to make connections where few exist even as I realize it adds little value. William Faulkner adviced that writers kill their darlings. Analogies should be near the top of the hit list. Refusing to see past an analogy’s shortcomings can only hurt your case. Bad analogies are likely to leave your readership confused, annoyed, zoned out–or led down a ridiculous line of argument by a faulty analogy that devolved into a discussion on traffic rules when the subject at hand was copyright.

Analogies are the darlings of many a geek with something to convey, but there is little to indicate that the receiving end yearns for more analogies. In my experience as a tech writer, I don’t think I have ever seen a request for comparing technology to other things when users are struggling to understand something. One of the most common requests, on the other hand, is more and better examples.

Killing poor analogies in three steps

If you want to avoid unhelpful analogies, this is my advice:

  1. Don’t use a car or traffic analogy, unless traffic and cars are part of the subject matter at hand. There might be a fantastic car metaphor for what you’re about to explain, but if so, it has in all likelihood been done to death already.
  2. Pick an analogy where at least one side will make sense to the audience, and where both sides make good sense to you. Go with something you know well and can talk or write about in a compelling manner. Don’t try to explain Transport Layer Security by comparing it to a kevlar suit if you have a limited understanding of either. Competent audience members will see straight through it, and your analogy will have weaknesses that you can’t even know about.
  3. Test your analogy on as many friends or family members as you can dig up, trying to make sure they have a somewhat different skillset than your own. Ask for their honest assessment of your analogy: is it interesting? Do they understand it? Is it helpful?
    • If yes, you have an analogy that seems to work well. Now try to avoid overselling it. “With ready-made WordPress themes, giving your blog a makeover is as easy as dressing up a paper doll” is a reasonable simile, while “WordPress blogs are paper dolls” is taking it too far, in my book.
    • If no, kill it, and skip using an analogy altogether. A straightforward explanation accompanied by one or more relevant examples will be every bit as helpful as an analogy. Probably more.
Categories
Administrivia

Starting a new blog. In 2014?

Suicide bunnies calendar, April 2014

Yes. I’ve had a personal blog in Norwegian since the early 2000s, covering miscellaneous topics, a blog that is mostly dormant these days. And yet, here I am plunging into a new blog project. What am I thinking? It’s April 2014!

Mostly, I’m thinking that I have things I’d like to say, experiences I’d like to share, on the subject of tech, development, “content”, and technical communications, throwing in some general geekery for good measure. And I’d like to connect with others who have things to say about the same things, so I will do it in English, my primary working language for the majority of the last 10 years.

I’ll be writing about technology and writing and related subjects, aiming to keep it interesting for writers not in tech and techies who don’t necessarily much writing.

So here I go! This concludes my hello world posting. The next one is coming up shortly and does not involve meta blogging.