How to use Readability Scores

 

Readability score resultsIf you need to make sure your writing is clear, the website Readability Score can help.

I’m not connected or affiliated to this website or its creator in any way, I just find it very useful, and wanted to share it with you.

Much of my working life involves writing, so to all intents and purposes I am a professional writer.

I want to show you why I find this site useful, and give you some recommendations on how to use it.

What is a readability score? What is a readability index?

The concept of a readability score (also known as a readability index) goes back many years, really hitting its stride in 1975, when Rudolf Flesch and J. Peter Kincaid built their Flesch–Kincaid readability tests for the US Navy.

The idea is that by looking at your writing, and making some calculations, we can figure out roughly how easy it is for somebody to understand what you’ve written.

It’s an automated calculation, so of course it’s not perfect, but it’s a very useful guide. The most common measures that these scores look at is sentence length, word length, number of syllables in your words, and the number of characters (letters) that you use.

Sometimes it’s difficult for a computer to count syllables accurately, so the measures are sometimes not 100% precise, but from a practical point of view that doesn’t matter.

There are two basic types of measures. The first is just a score, which doesn’t mean much by itself, but can be used to compare one piece of writing to another.

The second measure, which Flesch and Kincaid developed, and several others have followed, is more useful to us. It shows the average American school reading grade needed to understand your writing.

What are the most popular readability scores?

There are several readability tests that ultimately boil down to a US reading grade. This means that we can run several tests, compare them, and take the average.

Here are the big guns of the readability index world. They all work in different ways, and the links below take you to Wikipedia articles so you can find out more. They produce results of a US reading grade that are usually no more than two or three grades apart.

(Readability Score gives you these links when you see your results, which is nice.)

How does readability-score.com work?

This website was built and maintained by Dave Child, who’s based in the UK. I don’t know him personally, but he’s very friendly and responsive to email, if you have feature requests, etc.

The site is nice and easy to use, and looks good. You can either paste some text directly into the site (which is what I do), or upload files, or point the site to a URL web link that contains your text. The site can even monitor your links, such as your homepage, and alert you when certain readability thresholds are breached.

The results are very clear and easy to see, and I’m sure you’ll find it very useful.

You get to see the various reading grade levels for your writing, and an average.

You also get keyword density, ie how often certain words or two-word phrases appear. Personally I don’t need this, but if you write with SEO in mind it can be helpful.

Word count, sentence count, and average words per sentence are useful. I’ll give you some recommendations below for how you could use this.

The longest sentence is a crucial metric, and one that I asked the site author to add for me. (Impressively he added it within a day!) You also get the longest word, which can be helpful too.

If you are more than a casual user, there are very reasonably-priced subscription options, which help support the site.

A note on security and privacy: With sites like this, we always have to think about security and privacy. I’ve no idea whether this site (or any other similar site) stores your text, or does anything else with it. It probably doesn’t, but of course it could. (They do have a Privacy Policy.) So as always on the internet, it’s always best to assume the worst case scenario: don’t go pasting highly confidential documents into any kind of site like this, just to be safe!

How to use readability scores in your writing

Even highly intelligent and/or educated people (not always the same thing!) find it easier to read and comprehend writing that is at a lower reading grade. So no matter who you are writing for, whether it’s doctors and lawyers, manual workers, or the fabled “high-school dropouts”, a lower score is usually better.

The excellent book “Write everything right”, by Denny Hatch, (a long-time marketing man), is well worth a read. (Amazon UK  Amazon US)

It contains these facts from the Literacy Project Foundation, relating to American readers:

 50% of adults cannot read a book written at an 8th grade level

45 million are functionally illiterate and read below a 5th grade level

In other words, the average reading grade in America is 8th grade level. I have no particular reason to doubt that the UK is very similar.

The advice of Denny Hatch, which I agree with, is:

  • Keep sentences to 29 words or fewer
  • Write at 8th grade level or even lower if you can

Conclusion: an essential site for all writers

Here’s a screenshot showing the readability scores for this very article you’re reading now. (Click the image to see a larger version.) What do you reckon? Must try harder!

Readability score screenshot

A “fan” of simplicity

This blog post from Digital Amit is an oldie-but-goodie on a quick lesson in simplicity. This could be a useful story for you to tell when motivating your teams to keep it simple!

It compares two approaches to solving the problem of weeding out an empty box of soap on a manufacturing line.

Of course, you might argue that there should be a root cause analysis to find out why the box of soap was empty in the first place, but that spoils the point of the story!

Problems coordinating your project? Try a short daily stand-up meeting.

This article is very back-to-basics, but I think many people would still benefit from applying it. So here goes!

I was chatting to someone recently who’s involved in a project with lots of different departments within her company, including marketing, IT, finance, and third-party vendors. She said that it’s proving difficult to keep everyone coordinated with the status of the project, and with what needs to happen next. She’s also having problems making sure that all the different parts of the project will be ready by the time they are needed. This has been even more difficult during the summer holiday season, when many people are away from the office.

So what can be done to improve things?

First, of course, there are the standard project management techniques such as a Gantt Chart showing when each part of the project needs to be completed. This could even just be a list that gets pinned to the wall, or put on a website or wiki page so that everyone can see it. (If you’re interested in wikis, I’ve had great success with Atlassian Confluence wiki software.)

But one of the best ways I’ve found to communicate project status is to have a short meeting each day, at the same time every day, with everyone involved in the project. In agile software development these meetings are called Stand Up meetings (or “standups”), because often the participants are all standing up. The idea with this is that nobody really likes standing up, so it keeps people brief and to the point!

The meeting should last no more than around 15 minutes.

Make sure that each person gives an update that includes:

  1. What they did yesterday
  2. What they will do today
  3. Any problems that they have faced that could affect their work (often these are called “blockers”, since they are blocking a task from being completed).

Lots has been written on how standup meetings should work, but it’s really not difficult, so if you’re having problems coordinating a project, give it a go!

Tip for Conference Calls: Ban Speakerphones

One of the big problems with conference calls is that it can be hard to hear what other people on the call are saying. I wouldn’t consider myself to be hard-of-hearing but sometimes I really struggle to hear what’s going on. This is especially true when one or more people on the call are using speakerphones: hands-free phones (that often look like UFOs) that people gather around in conference rooms.

Problems with speakerphones:

  • They pick up background noise
  • They pick up echo in the room
  • People are very tempted to shout into a speakerphone, because they are not physically close to the microphone, which can lead to an unwanted hostile quality in the voice!
  • Volume is inconsistent: speakerphone users are often very loud on the call, or very quiet, or a mixture of both (great to blast out the eardrums of everyone else on the call!)
  • Bottom line: voice quality is usually very poor, so communication is also poor.

One tip I’ve found is to ask participants not to use speakerphones on conference calls. Instead, ask everyone to use a standard phone, even if they are in the same room together. This way, everyone is speaking into their own microphone, which is held close to their face. Call quality is much clearer, and communication is much easier.

The same is of course also true when using Skype, GoToMeeting, GoToWebinar, or other Voice Over IP (VoIP) services.

Ten reasons to use a wiki for documentation

I’ve been very impressed by how useful the wiki has been in real world use: here are the reasons that have made the wiki very successful for us.

Thought Wikipedia was the only wiki? Think again! A wiki can be a great help in keeping all your documentation up-to-date and easily accessible. In this article I’ll explain why you should give a wiki a try.

For a couple of years now, I’ve been working with a FTSE 100 company that uses wiki software for keeping its internal IT documentation. This includes notes relating to development, testing, and how the various IT systems and business concepts work.

I’ve been very impressed by how useful the wiki has been in real world use, so I thought I’d share the reasons that have made the wiki very successful for us (and for me in particular, as a documentation author as well as a reader).

As knowledge management becomes ever more important, most companies should give serious consideration to using wiki software, not just within IT departments but in the wider business.

The wiki software I’ve been using is Atlassian Confluence, but no doubt using other wiki software will realise some if not all of these benefits.

So in no particular order, the benefits that I’ve personally found with using a wiki for documentation are:

1. Easy to find information

A wiki puts information is all in one place and is fully searchable.

With hundreds of topics, potentially written by hundreds of users, it’s easy to end up with a labyrinthine folder structure of Word documents that sit gathering virtual dust because nobody can find them. For example, I had been working with the company for about 8 months before somebody pointed me to some useful documentation that I could have used right from my first day with them!

A searchable wiki makes it quick to home in on exactly the information you require.

2. Easy to tell how up-to-date a document is

I recently read a corporate document, that’s still being issued, that discussed upcoming changes for 2005 – it’s now 2014 as I write this!

A wiki breaks a large topic into a series of sections, one per page, and with automatic date tracking for when each section was last updated you can easily say how up-to-date or out-of-date each individual section is.

If you read a sentence in the documentation similar to “John recently did some work on the payment system”, which is bad because it isn’t specific, you can at least roughly narrow down when this time period might have been. In a Word document that was started 10 years ago and periodically updated, you would have no idea as to even which year it might have been!

Since out-of-date documentation cannot be trusted, and might be either wrong or actively misleading, being able to tell the precise age of the documentation you are reading greatly helps with understanding how much or how little you can trust the documentation.

3. Easy to update, so gets updated more often

Updating the documentation is as simple as clicking the bookmark in your web browser to get to the wiki and making a few changes. There’s no need to fiddle around with version control or re-issuing documentation.

It’s also easy to do a very small change here and there, when you have time, and then build up the documentation over a period of time. I have wiki pages that I update probably once a week as I learn a new snippet of information. This contrasts with the approach of writing documentation into Word documents, where it feels more like you have to write a whole manual or definitive piece of documentation all in one go and then more formally distribute it.

So because wiki documentation is so easy to update, it tends to be more up to date.

4. Easy version control and roll back

A wiki lets you easily go back to a previous version of a page. You can take a more active approach to updating documentation, because you know you can never really break it, and can always roll back if you put the wrong thing in the wrong place.

5. No need for a single document owner

There are no bottlenecks centred around individual people for writing documentation or putting together everyone’s contributions. If you’re reading or reviewing documentation, and you know that something is wrong or out of date, you can update it immediately, without asking permission, and without waiting for somebody else. This helps to keep documentation up to date.

6. See who wrote what

Depending on who wrote the documentation (and your assessment of their competence!), you know more about the likely quality of the documentation, and exactly who to speak to if you have questions about it.

7. Links within the documentation to help users navigate

Being able to easily add links to other relevant sections of the documentation means it’s easier to guide readers to the precise areas of the documentation they will find more useful, and easier to make sure that the reader doesn’t miss other important topics related to the section they are currently reading.

8. See a list of recent edits to know who has been working on what

Atlassian Confluence has a dashboard view showing who has been editing what. It’s like a running commentary showing all the changes that have been made. It makes it easier to see who is working on what areas of the documentation.

9. Notification of changes

It’s easy to set up notifications for sections of the documentation that you are interested in, and then be told when those sections are updated. This way you can be made instantly aware of when important information might have changed.

10. Easy team collaboration for fast-moving information

For sections of the document relating to project status, or what will be released in an upcoming software release, where several authors may all be making changes in the same day, the wiki environment makes it very easy to make and share these changes.

When NOT to use a wiki

There are some downsides to using a wiki, largely relating to making sure that information is kept secure, but any documentation written down can theoretically be disclosed outside the company anyway, so this isn’t an issue solely related to wikis. Wikis can restrict access to certain pages to certain users anyway.

Wikis can tend to be quite free-form, with different authors doing things in different ways, so sometimes you need to try and impose a bit of structure.

If you need full distribution and approval controls, perhaps when issuing documents to third parties, then you might want to consider a fully-fledged Document Management System, but they are quite heavyweight and expensive, and you’re unlikely to really need it.

Conclusion

I’ve found that using a wiki for documentation brings the documentation to life. It’s no longer an old, stale and outdated document that gets written once and then forgotten about, never updated and never read. It keeps the information up to date, prominent, and searchable. I’ve been very impressed with using a wiki, so I recommend that you give it a try.

Action Points

If you want free wiki software then consider MediaWiki, which is what Wikipedia runs on. If you’d prefer a hosted wiki that you can get started with immediately, there are a variety of free and paid services.

Technical Debt: say it like you mean it

When I hear people using the phrase “technical debt”, it’s mostly used as a buzzword. The actual meaning is lost. It’s a euphemism. When they say “There is a lot of technical debt on the project”, senior people nod sagely … and then ignore it.

What is technical debt?

It’s fashionable these days to talk about “technical debt”. If you need a primer on this, Martin Fowler gives a good concise explanation of Technical Debt.

The concept itself is fair enough: each time you hack something into your software code without doing it properly you store up problems for the future, and these problems are added to your technical debt. In that sense it’s a useful way to think about the problem of how a code base gets polluted and harder to work on as time progresses, as the debt either mounts up or gets tackled and reduced.

So far so good. But when I hear people using the phrase “technical debt”, it’s mostly used as a buzzword. The actual meaning is lost. It’s a euphemism. When they say “There is a lot of technical debt on the project”, senior people nod sagely … and then ignore it.

That’s because “technical debt” doesn’t really sound that bad. It’s the same reason the military say “collateral damage” rather than “slaughtering innocent women and children” – it just tends to sound a bit better!

If you could put an accurate financial value on technical debt, as you can with real financial debt, then maybe a conversation on technical debt would have some meaning. There have been some efforts to quantify technical debt, but you might argue that the methodologies are vague and the final numbers don’t really stand up to scrutiny. Maybe they never could.

Technical debt as a euphemism

So what I really dislike about the phrase “technical debt” is the Euphemism Factor, the way it can pull the wool over the eyes of management, and even people on the project, and make them think that things aren’t as bad as they really are.

Let me put it this way. If you were the boss, and a project manager was reporting to you on their progress, what would you think if they said this: “There’s some technical debt on the project, so it will be quite challenging to add the new features.” That’s a phrase I’ve actually heard someone use. And I saw the boss take it, nod his head, and move on to something else.

What the project manager actually meant was, “This code base is so wrecked we can’t do anything with it! Every time we try to add something new, we break a dozen other things. We’ve built fudge on top of fudge on top of fudge, and the whole thing is about to come crashing down around our ears!”

Let’s face it, what we’re really talking about here is honest conversation. Take a look at some of Jack Welch’s books. (Jack Welch was the CEO of General Electric from 1981 – 2001, and is widely held to have been a highly successful CEO). He often talks about the power of being what he calls “candid”. You might choose to call it honesty, frankness, or being straightforward. Or as Dan Kennedy puts it, “No B.S.”

Action points

My recommendation is to move away from euphemisms like “technical debt”, unless you’re attempting to do some kind of serious financial quantification of it, and move towards concrete, specific comments that quantify the problem in terms that are meaningful to the business, and emphasise the potential productivity that is being lost.

So maybe what the project manager should have said was something along the lines of, “Due to the speed with which we’ve had to release new features, and the number of different developers that have worked on the project over the years, the code base has got really difficult to work with now. We’re finding that we break quite a few things when we add new features, so we’re always treading on eggshells, and that slows us down a lot. We haven’t got enough automated test cases to give us confidence that we’re not breaking the old things when we add the new things. So adding this feature is going to take us at least 4 weeks, when if the code base was cleaner we could do it in 2 weeks at the most. The last feature took us 6 weeks, and we think really it should have been 3 weeks, but we broke existing features X, Y and Z in the process, and fixing them took us 3 weeks.”

It takes a bit longer to say, but it shouldn’t take long for the message to sink in!

I’m obviously not suggesting charging in with both boots and telling the CEO in no uncertain terms that we’re all doomed! But what I am suggesting is that you’ll get better results if you move away from vague terms and management speak, like “technical debt”, that can be brushed under the carpet and ignored, and start talking in practical, quantifiable terms about the poor state of your code and how it’s affecting your productivity. Then you might get the chance to do something about it!