Forums

Hey folks ...

for all of you that need to re-read the [b]clarity-index-thing[/b]. Follow that link [url]http://www.au.af.mil/au/awc/awcgate/army/clarity_index.htm[/url]

These were again two good ones ;) thanks to MARK and MIKE

André

aspiringceo's picture

Back in the days of windows 3.1 Ms word had a similar tool called the fog index. It was similar to Mark's method ie

1. Count the number of words in the sample - 88

2. Count the number of sentences - 6

3. Count the number of big words (3 or more syllables) - 6

4. Calculate the average sentence length.
Divide the number of sentences into the number of words - 88/6 = 14

5. Calculate the percentage of big words.
Divide the number of words into the number of big words - 6/88 = 7%

6. Add the avg sentence length to the % of big words - 7 + 14 = 21

7. Multiply the result by 0.4 - 21 x .4 = 8.4

Fog Index =8.4

The "ideal" Fog Index level is 7 or 8. A level above 12 indicates the writing sample is too hard for most people to read

johnodavidson's picture

I could find the "fog index" but I did find this:

Display readability statistics
1) On the Tools menu, click Options, and then click the Spelling & Grammar tab. 2) Select the Check grammar with spelling check box. 3) Select the Show readability statistics check box, and then click OK.

Now when you run Spelling and Grammar you get statistics.

ccleveland's picture

When you use the method olivr2 described you get a couple of indexes that are very similar to the M-T method.

Here's the Word-help content of the readability indexes:

[quote="Microsoft Word Help"][b]Readability scores[/b]
When Microsoft Word finishes checking spelling and grammar, it can display information about the reading level of the document, including the following readability scores. Each readability score bases its rating on the average number of syllables per word and words per sentence.

[b]Flesch Reading Ease score[/b]
Rates text on a 100-point scale; the higher the score, the easier it is to understand the document. For most standard documents, aim for a score of approximately 60 to 70.

The formula for the Flesch Reading Ease score is:

206.835 – (1.015 x ASL) – (84.6 x ASW)

where:

ASL = average sentence length (the number of words divided by the number of sentences)

ASW = average number of syllables per word (the number of syllables divided by the number of words)

[b]Flesch-Kincaid Grade Level score[/b]
Rates text on a U.S. grade-school level. For example, a score of 8.0 means that an eighth grader can understand the document. For most standard documents, aim for a score of approximately 7.0 to 8.0.

The formula for the Flesch-Kincaid Grade Level score is:

(.39 x ASL) + (11.8 x ASW) – 15.59

where:

ASL = average sentence length (the number of words divided by the number of sentences)

ASW = average number of syllables per word (the number of syllables divided by the number of words)
[/quote]

I expect counting the number of words with > syllables is a lot easier than figuring [u]average[/u] syllables per word if there's no automatic calculation.

CC[/u]

Mark's picture

Hey! We talked about this on the cast! This isn't news...and is part of the reason FOR the cast...it's awful.

:wink:

Mark

asteriskrntt1's picture

I suspect Mike (or any of our programmer friends) could quickly generate a Macro for Word that generates the Clarity Index score.

*RNTT

ccleveland's picture

[quote="mahorstman"]Hey! We talked about this on the cast![/quote]

:oops:

I missed that. I must have been focused on a traffic jam-up at the time. What was that about being less effective when multi-tasking?

CC

Mark's picture

We will provide this tool, folks.

That help?

Mark

Nik's picture

Building that clarity tool is harder than it looks. I spent an hour this morning stumbling through definitions of syllables to try to find an algorithm and ran into a huge problem: English is HIGHLY irregular.

See, a syllable, by definition, contains a single vowel and a leading, trailing, or leading and trailing consonant. Except for some syllables which, er, don't. (e.g. Silent "e" in the middle or at the end of a word, the "ious" at the end of "delicious" has three vowels but is still a single syllable, the "aa" at the beginning of "aardvark," and the list goes on...)

In the end, counting that stuff by hand and doing the math is pretty quick when you're just running through a page or so of text. I suppose it depends on whether you want accuracy or super quick automation.

Mark's picture

We. Already. Have. It.

And you're right... you don't need it for 200 words or so. NOBODY is that busy.

Mark

rwilson's picture

I tried the clarity index on a technical proposal I had recently written. There were many words with 3 or more syllables in my sample. The vast majority of these were technical words that I feel are succinct and appropriate. To avoid these words would not improve the readability of the document.

I was hoping the clarity index would be of general use for my writing. Is there a modification to the algorithm necessary for technical writing?

Thanks!

p.s. first post, love the podcast!

Mark's picture

Glad you're with us!

No, there is not a technical modification to the index. Before I tell you what I recommend - and surely you've thought of this - I will say I've written plenty of technical proposals, and have NEVER had to use this. I've found that many technical words are NOT necessary.

To work around what *might* be an issue, calculate your ASL normally. Then calculate your large words score. Make sure the problem really is with large words. Then, determine how many 3+ syllable words would cause your score to be 15 in this part of the calculation. After doing this several times on similar writings, you'll end up with a new (higher than 15) rough target for your technical writing.

If you like, please post a 200-300 word cogent sample here, and I'll be happy to take a crack at its clarity index.

Mark

rwilson's picture

Mark,

I'd be happy to post the sample I used if it would help. It is shown below. I had to obfuscate a bit of the content to protect corporate secrets. The acronyms like IJK were all different acronyms or less than 3 syllable words.

[quote]ABC was designed first and foremost to meet the needs of interchanging data between applications. The most common interchange is between interactive and batch-oriented analysis applications. However, interchange between various interactive applications is also an important use case. The usage scenarios for these interchanges do not require using ABC for interactive persistence of the data model. However, it was always a future goal to expand to the scope of ABC to cover the interactive data model persistence.

A key difference between interchange of data between applications and persistence of interactive data is the size and complexity of the transactions. In the interchange scenarios, you can think the writing of data as one large transaction. If the transaction fails (e.g. out of disk space), then the entire interchange doesn’t occur. In the interactive persistence scenario, there are many smaller transactions that must always leave the database in a good state. The typical interactive persistence transaction boundaries are user-initiated save operations. These transactions represent the changes or delta to the data model since the last save operation.

The XYZ Update mechanism causes the conversion of IJK Model data to the RST model whenever features are created, modified or deleted. This same mechanism will be use for ABC-ification.
[/quote]

words = 205
sentences = 13
long words = 53

205/13 = 15.8
53/205 = 25.8
Total = 41.6

Much thanks!

RichRuh's picture

Here are some suggestions.

ABC was designed first and foremost to meet the needs of interchanging data between applications.

"first and foremost" and "to meet the needs of" are not necessary. How about:

ABC was designed to interchange data between applications.

Now remove the passive voice:

ABC interchanges data between applications.

Now, I don't know if the word "interchanges" has a special domain-specific meaning here. If it doesn't:

ABC exchanges data between applications.

This drops the word count from 15 down to 5. The count of long words drops from 2 to 1.

I think you could make similar changes to the rest of the sample to improve the clarity score.[/i]

davefleet's picture

Hi,

From reading the text you posted, I have a few recommendations for ways you could improve your effectiveness here.

I advise you to stick to a few key principles when writing. I work in communications, where clear writing is king nowadays -- we use these principles at work, and they're remarkably effective (and similar to the techniques M&M mentioned in the writing podcasts):

1. Use short, simple sentences. Avoid jargon and acronyms.
2. Use the active voice
-- e.g. "ABC was designed first and foremost to..." could be, "We designed ABC to..."
3. Use strong, active verbs — don’t rely on ‘to be.’ Resist starting sentences with “there are…”, “it is…”
-- e.g. "In the interactive persistence scenario, there are many smaller transactions that..." could become, "Interactive persistence uses many smaller transactions that..."
4. Avoid turning verbs into nouns
-- e.g. "The XYZ Update mechanism causes the conversion of IJK Model data" could read, "The XYZ update mechanism converts IJK model data...
5. State ideas positively where possible
-- "...entire interchange doesn’t occur" becomes, "..."the entire interchange fails."

Also consider -- many people (especially academics) use long words without thinking if they're really necessary, and end up with something that no-one wants to read. Writing clearly doesn't mean dumbing it down - it means making it easy to understand.

I use the 'mother test' -- would my mother understand it if I read it to her?

That's enough of my ranting -- hope this helps!

Dave

iainmagee's picture

Hi there,

Welcome to the forums. Some really good advice from davefleet & RichRuh I think.

[quote] The vast majority of these were technical words that I feel are succinct and appropriate. To avoid these words would not improve the readability of the document. [/quote]

I disagree. I'm a technical bod! I read & write technical stuff all day and I had to read your paragraph carefully (twice!) in order to understand it's meaning. That's not good! :)

Your audience may be technical people but I would agree that a good rule of thumb is to write as if you're writing to non-techies. The recipient will have enough to think about in understanding the concept of what you are saying without having to waste "brain power" deciphering long wordy sentences. Your recipients will love you for short to the point reports in the active voice. And the chance of them actually reading it will increase also!

"ABC exchanges data between applications." is just SO much better than your example line.

Readability is something I struggle with on a daily basis when writing. I usually find that it's because I'm using 14 words when 3 will do .... or worse, when the author finds that he has inadvertently slipped into passive voice again :oops:

Iain

PattiBarcroft's picture

Following is a great example of undue complexity that was recently posted at www.accidentalcreative.com

1+1 = [(27/3)/3]-1

I have begun asking my technical team, what is the 1+1 information. I think that we often try to impress others showing how hard we have worked on something or how smart we are, by explaining 27 divided by 3 blah blah blah, instead of stream-lining our communication.

My 2 cents - technicians who cannot overcome this temptation will remain technicians, at least in our environment because people stop listening to them.

Patti

rwilson's picture

Wow! I'm very impressed that you all invested time to help me with this example. Thank-you very much!

Rich - you caught me with the first & foremost. I was reinforcing the purpose of ABC but it doesn't add anything here. Yes, interchange is domain-specific and is used similarly to exchange but has some key differences. Great advice.

Dave - you example in 3 is great! That seems obvious to me after you've pointed it out. Again, great advice.

Ian & Patti - Also, great advice.

Well, I'm glad I posted my sample. The feedback is very helpful. I'm going to get to work on becoming a more effective writer.

Best regards.

Mark's picture

This is not a case of technical jargon, but of writing style and choice of words. I am not even sure that your message was clear in at least one case. Your second paragraph body doesn't follow from its first/topic sentence. Please do not read my sample as an endorsement of the larger construct.

I have probably overdone the "clarity" in an effort to show that the problem is word choice, and one could quibble with changed meaning...but that just shows that the original wasn't clear. My guess is that you could take my sample and change 2-3-4 things and still have a great score and get better reader understanding...which is the point.

Nevertheless, here it is, rewritten, with stats below.

[b]ABC is designed to exchange data between programs. The most common use is between interactive and batch applications, followed by use between interactive programs. The use cases for interactive exchange do not require ABC for persistence of the data model. That is a future goal.

Transaction size and complexity is a key difference between application data exchange and data persistence. When programs exchange data, they write data in one large piece. If the exchange fails (e.g., lack of disk space), none of the data is exchanged. With persistence, many smaller transactions leave the database in a good state. User "saves" are typical transaction boundaries. These transactions show the delta to the data model since the last save.

The XYZ update converts data from the IJK to RST model when features are added, changed, or deleted. This process will be used for ABC also.[/b]

Total words: 143.
Sentences: 13.
Long words: 19.

ASL = 11
LWP = 13

Total: 24.

rwilson's picture

I'm glad I put up this example. The feedback has really helped me appreciate the power of effective writing techniques. When I re-read it, the message wasn't clear to me either.

Some background on the text might be helpful. It is 200+ words that I grabbed from the middle of a large document. The last paragraph was truncated.

Here is a new version after making some edits. The first two paragraphs become one and it makes more sense now. It should be more readable too!

[quote]We designed ABC to interchange data between programs but the goal is to extend ABC for interactive data model persistence. Transaction size and complexity is a key difference between these two uses. Interchange uses one large transaction and persistence uses many smaller ones. If a transaction fails the entire interchange fails, but with persistence it leaves the database in a good state. User saves are the persistence transaction boundaries and these represent the changes or deltas to the data model since the last save. Interchange boundaries are the entire data model.

The XYZ update mechanism converts IJK model data to RST model data. This occurs when features are created, modified or deleted and will also apply to ABC.

118 words
8 sentences
23 long words

118/8 = 15
23/118 = 19
Total = 34
[/quote]

This is getting clearer but more improvements exist. If I switch interchange for exchange the score becomes 31. Unfortunately, I really do have to use interchange over exchange.

Well, thanks again for all your help. By working through this example I am convinced that the clarity index will definitely help improve my writing.

Best regards!

Mark's picture

Well done! I like where you're headed, and glad the tool showed you some ways to get there.

Mark

(You could get a lower score - but more importantly better readability - by using exchange rather than interchange, and changing created to added, modified to changed, etc. Really think about those 3 syllable words! - H)