Readability is a web-based survey built in Pylons. Its primary purpose is to determine the most readable arrangement of text within a given set of constraints.

A New Yorker piece by Malcolm Gladwell entitled "The Ketchup Conundrum" is used as the sample text for all readability tests. Excerpts from it have been divided into six sections with the following word counts: [(1,188),(2,185),(3,105),(4,154),(5,264),(6,204)]

The full article is available here:

The variable components of the paragraphs are as follows:
Text Size: [12px, 14px, 16px] Line Height: [1, 1.5, 2] Width: [480px, 640px, 800px] Typeface: [Helvetica, Georgia, Comic Sans]

The survey is divided into three phases: 1. User indicates preference among 4 pregenerated designs based on a cursory glance. The user can move freely between each design using a navigation/rating frame positioned at the top of the page. 2. User creates what they believe to be the most readable design by manipulating the four categories available. 3. User reads an excerpt from The Ketchup Conundrum over the span of 6 pages, each with a different design. Reading time is tracked in the background and logged in WPM.

Installation and Setup

Download from the hg repository:

hg clone

Go into the readability folder in your terminal and type the following commands:

python develop paster setup-app development.ini

Now run it:

paster serve development.ini

To modify the variables tested, alter the values in readability/util/ and it will spit out a list of all possible combinations. Set the one you want to serve as control to favorite. This will make it be at place 0 in the list. Save this list as combos in readability/lib/ so it's easily accessible by Also change the values for c.typefaces, c.font_size, c.line_heights, and c.widths in the create function in readability/controllers/ to alter the variables.

To change the story used, save a new story as a text file in the text directory and edit to your preferences. Update the wpm count in to reflect the wpm counts of the 6 newly created passages.

To alter the story, edit the files located in the text folder. Make sure to put the wpm counts in readability/controllers/ when you've selected and split up your text.

Then you are ready to go.