Readability? Does it matter?


#1

I am hoping this produces some good discussion.

What are your thoughts to this quote I found:

Deborah S. Bosley, a clear-writing consultant and former University of North Carolina English professor. "Academics, in general, don’t think about the public; they don’t think about the average person, and they don’t even think about their students when they write,” she says. “Their intended audience is always their peers. That’s who they have to impress to get tenure.”

Do you feel we as technical writers do the same? Do we write to our peers and engineers in order to impress them or do we write to our audience? What tips or steps would you say help you write to your audience? Do you take into account their reading level? If yes what do you do to ensure your writing is at a particular level and what reading level do you aim for?


#2

I try to write at a low reading comprehension level. People reading documentation aren’t reading for enjoyment. They want information quickly. Simple language also helps translators. Most translators aren’t native English speakers.

  • Don’t say anything that doesn’t need to be said.
  • Avoid compound sentences. Prefer simple, choppy sentences.
  • Avoid adjective clauses that cut your sentence in half.
  • Use the words that people are most likely to understand.
  • Use paragraph breaks and bullet lists frequently.
  • Write in the second person. Use direct imperative sentences.

Basically, do the opposite of whatever you learned in a creative writing class.


#3

Today from twitter, a propos of this discussion:

If technical writers are writing to impress peers (including engineers) instead of for our audience, we belong in a different profession. Or we need serious attitude adjustment :wink:


#4

Bashing my article already? :wink:


#5

When I submitted my article http://opensource.com/business/15/11/how-reader-friendly-are-your-docs, I found this article http://www.theatlantic.com/education/archive/2015/10/complex-academic-writing/412255/ and thought that maybe now is the time to bring all these ideas to the table and have a discussion on readability. On the one hand, there are cases where our audience is very intelligent and over-simplifying the content would be a source of contention. On the other hand, statistics show the opposite. The reading level of people around the world is much lower than we thought. If we are going to make our docs readable by the larger community, we need to take the plain simple fact that many people struggle at reading English into consideration. So keep the comments coming!


#6

Au contraire! (But failing to check your forum username before I posted :-()


#7

Hehehe… if you were writing to your audience… We would “ensure” our writing is at a particular level. Cuz I don’t think we can buy “insurance” to “insure” our writing. (Dang, I wish we could, though! Wouldn’t THAT be cool? Like insuring a supermodel’s legs, right? Hahaha!)

I write for users. I keep it simple, partially because I’ve always written content that would be localized but also because I write for a global audience. But I never “write down” to the user. Writing to a sixth grade level or something like that is just ridiculous. Know your audience is the first step of being a successful writer, no? Then be sure you know your product. If you can write intelligently, the rest is just, well, icing on the brownie! (Craving chocolate today for some reason, so yeah, I went there!)

Oh, and for goodness sake, please don’t forget to number those steps!!! (Yeah, why do people do that? Steps embedded in a paragraph do no one any good. Why do I keep encountering this? Why oh why?)

…sue


#8

Audience.

That’s the word that comes to mind. A good part of my audience is highly intellectual – some can and do write in an academic style, as suggested by Laura’s linked article in The Atlantic. (btw, I think that article went a bit far – IMO, academics who write for academics have their own language)

So while it’s not always possible, I feel better about my writing when I can “simplify” things to sentences such as:

“See Spot instantiate”

Then I can go into details, with confidence that my audience understands the points I’m trying to make.


#9

Well, a lot of academic writing is terrible and jargony and unfollowable. But some of the best academic writing has literary aspects, and so does some of the best journalism–there is a pleasure in writing for people who have an advanced vocabulary and the ability to follow a complex argument. That isn’t the same thing as baffling people to flex your ego.

I don’t think all technical writing needs to be in Orwellian Newspeak or simplified English, either, but sometimes it does. Who is using your docs? Do they just want to get information and get out, or are they motivated to understand deeply? Do you NEED translation or is it an afterthought? All these things matter. For end user docs I definitely find myself hacking out the semicolons and shortening my sentences, but I figure community managers can handle some humor and a dependent clause or two.

tl; dr: know your purpose and audience. Users aren’t all the same faceless person.


#10

Ideally, we should be writing for the audience wconsuming our material, but the problem is understanding who they are. Our customer service VP periodically comes to me asking me to “dumb down” some of my documentation to about a third grade level. But I don’t always write to just one audience. For instance, I write for “general” customers, but also for developers, so it’s a matter of adjusting what and how we write given who will be reading our documentation.

For general customers, I consult with our support team to make sure I’m writing at their level, and I work with our developers to make sure my more technical docs are hitting the mark.


#11

Readability scores only tell us a limited amount. I think there are two more important things to bear in mind when writing for an audience:

  1. What ideas and concepts a reader understands are far more important than the reading level. Words don’t have absolute meanings. We combine them to suggest stories and ideas that we assume our audience is familiar with. If we get that assumption wrong, the audience will struggle to understand even if text is written at a grade 6 level. If we get it right, they will still have a good chance to understand even if we write at a grade 12 level. Failure to understand is far more often caused by an unfamiliar concept than a long sentence or a long word. The curse of knowledge is the biggest enemy of any writer because it makes us think that everyone knows the ideas and stories that we know. Fighting the curse of knowledge is far more important than keeping your reading level low.

  2. People who read at a low grade level actually don’t read at all. Anyone who is in the habit of reading regularly reads at a high grade level – their level improves with practice. People who read at a low level may be part of your user base, but it is highly doubtful that they are part of the readership of your documentation. When they don’t understand something, they are not going to crack the manual, they are going to ask a colleague. People don’t use strategies they expect to be difficult and unsuccessful. Even if you write for them, it is unlikely that it will occur to them to read. Much better to write for the few people in your user group who actually do read, and who are the resource for everyone else.

Mark


#13

good point Sue - and a stronger reason why I need to read what I type!