I'm one of several technical writers at Maplesoft.  It's our job to craft the text in our brochures and user stories, and on our web site.  We all have differing styles, but we share a common goal; we want to write in a manner that’s technically compelling but simple to understand.

After recently exploring Maple’s string manipulation tools, I was surprised to find a command that measures the readability of a sample of English text.  It seems that as well as making you a better mathematician, Maple will poke and prod you into being a better writer.

StringTools[Readability] returns a measure of readability called the SMOG index (but, when asked, will also give the Flesch Reading Ease, Flesch-Kincaid Grade Level Formula, Automated Readability and the Coleman-Law indices).

These measures do not gauge the quality of the writing, its grammatical correctness, or account for specialized discipline-specific vocabulary. They simply use guidelines determined from in-the-field studies (largely conducted in the US) to quantify the degree of education or effort it takes to understand a sample of text.  Additionally, the calibration of the results against the required reading effort is only meaningful for readers whose native language is English, and whose schooling resembles that of the US system.

The SMOG index wins an award for the most amusing acronym of the month: Simple Measure of Gobbledegook. It's calculated with the following empirical formula.

 It returns the years of education (that is, the US grade level) required to completely understand a sample of text.  Typically, Newsweek has a SMOG index of 10 to 11, the New York Times 13 to 15, and the Harvard Law Review 17 to 18.

I was recently asked to describe MapleSim in less than 70 words; this was the result:

MapleSim is a tool for multi-domain physical modeling and control systems development.  Physical components and signal-flow blocks can be connected to create models that map onto the real system. It features an integrated environment in which the system equations can be automatically generated and analyzed, and new physical components created. It contains tools for optimized code generation, controls analysis and design documentation.

This has a SMOG index of 15.5, which implies the reader needs a university education for complete comprehension.  Since that’s the target audience, I guess I’m in the right ballpark.

As I write this post, I know I’m guilty of making many readability errors.  Are my fellow Maplesoft bloggers as guilty?

To answer this question, I used Maple to calculate the SMOG index for all the blog posts on Maplesoft.com (but first stripping out code snippets or URLs that would distort the score).  The top 10 and the bottom 10 scores are given below.

Well...it appears that I’ve written some of the most readable posts and the single least readable post.  The two least readable blog posts are those that explore abstract, high-level ideas (and hence demand more sophisticated writing), while the most readable blog posts are essentially opinion pieces.

Other than that, the only conclusion we can make is that good writers tend to write to the level of comprehension of the intended audience and the material; they don’t unnecessarily dumb down the sophistication of their writing to the lowest common denominator, or write to a level that’s beyond the scope of the material.

I’ve attached a Maple worksheet that helps you explore the readability of text using all of the measures in StringTools[Readability].  You may want to use it to write a more readable blog post than this one.