Readability is the Only Metric

What you can measure, you can improve.  Whether you need creative content for e-commerce or step-by-step instructions for machine repair, you must reach your audience.   Microsoft Word offers metrics for readability, from the Grammar and Spelling checker, under Tools.   We have no quantified methods for creativity, invention, cleverness, or insight.  We can measure word length, sentence length, and sentences per paragraph.  

It is not perfect. In fact, it can be gimmicked, tricked, and gamed.  But it works.  On a project to develop a multiprocessor industrial controller, the other technical writer was a young guy from an advertising agency.  He did not know manufacturing, but he was good writer.  We enjoyed finding some of the many failings in the MS-Word readability scales. We still used them.  They proved that we documented the interactive debugger to a 6th grade reading level.  When the line is down, no one is looking for a literary experience. You need answers.

Texas Department of Information Resources
IT Policy - Originally at 12.9 reading level

Same IT Policy - Rewritten to 12.0 reading level.

Of the 300,000 main entries in the Oxford English Dictionary, only 3,000 are Basic English; and most of us speak only 10,000 distinct words.  The average college-educated American recognizes about 100,000 words.  Whether "fardels" in that list is putative.  So, Hamlet's rhetorical question might pass the readability score, but not carry meaning.  Whether "putative" is in your speaking vocabulary may be arguable.

The fact remains that we have an objective measure for readability. 

Also on Necessary Facts
Visualizing Complex Data
Documentation is Specification
The Art of Typography
 The Genius of Design
How to Hire a Technical Writer

How to Hire a Technical Writer

Readability is the only metric.  Microsoft Word offers a readability score under the Grammar & Spelling checker off the Tools menu.  The Readability score has flaws; and it can be tricked.  Those are old problems.  But even a stopped watch is right twice a day.  A programmer can write their own lexical analyzer.  It is just a parser with more rules.  Back in 1990, I wrote one in Fortran to prove to a manager from Digital Equipment Corporation that I write technical documentation at a ninth grade level.  It is not that programmers, engineers, or accountants cannot read.  Rather, when you are in trouble, you need answers.  You are not looking for a literary experience.

 "Austin on Rails" is a meetup for Ruby on Rails software developers.  On Tuesday, May 28, I will be the "Introductory" speaker.  My topic will be "Documentation for Developers."  A software developer can rely on a hefty toolbox of programs for planning code.  Those plans are among the key documents.

Warnier-Orr for Greeting Guests

Ideally, the user manual is the first product. I look to the Warnier-Orr method for that.  According to Warnier-Orr, you start with your intended final output and work back to the primary inputs.  Warnier-Orr helps to plan large data structures.  It can include decisions and loops. Mostly, however, other tools make that work easier.  

Traditional flowcharts are well known. However, they have their own grammar, which is often violated.  For example, lines should not cross.  If they do, you have a potential problem in the flow of work.  Ideally, you should be able to "pick up" a flowchart by its Start, "shake" it, and have it "hang loose" with no tangles.  

For applications with deep and broad arrays of processes, the Nassi-Shneiderman method delivers clear pictures.  

Any significant project will be documented best with several tools. Narratives are among them.  Good technical writing uses short, declarative sentences.  Active voice identifies responsible parties.  The present tense and indicative mood deliver the sense of reality, and intention of purpose.  Convoluted sentences built from subordinate and dependent clauses in passive voice and conditional mood and future tense are concatenated confessions that this stuff should not be worried about.  If it is important, then say so.

Nassi-Shneiderman
for Order Entry

Managers who do not publish professionally think that they need to find a writer who knows some specific package.  After all, their firm has an investment in FrameMaker or InDesign, or RoboHelp.  That investment is quantifiable.  But they never ask me to quantify the readability of my work.  They assume that anyone who claims to be a writer must be good at it.  

Worse, a pernicious sense of democracy lets them believe that all writers are created equal, that we are endowed with interchangeable skills, and replaceable talents, that among these powers are grammar, syntax, and vocabulary; that technical writers are given to project managers to enhance the value of their products, and that when users, customers, and clients cannot find fitness or merchantability in the product, then a long train of abuses will be consequentially deflected to others.  

But I say to you, blessed are the writers.  Ours is the world of ideas.  We are the dream makers.  A writer who does not publish poetry cannot publish schematics.  

You need a master's degree level of literacy to understand the Declaration of Independence.  A child can understand the Sermon on the Mount.  Millions of people have died as martyrs to their religions.  Far fewer went to the barricades for liberal democracy.  Communication matters.  If you  believe in your product or service, then you want other people to accept its truth: you want committed customers.  Information systems win loyalty with technical documents that are alive with the truth of value in the product.

Previously on Necessary Facts: "Documentation is Specification" here.

The Sermon on the Mount is readable at Grade 5.3

Grade level 18.0 to understand the
Declaration of Independence

ALSO ON NECESSARY FACTS
Knowledge Maps
Readability is the only Metric
Documentation is Specification
The Genius of Design
The Art of Typography 

Sándor Kőrösi Csoma

He walked from Hungary to Tibet and brought the language of Tibet to the West.  His grammar of their language is also the foundation of our knowledge of their religion because he worked from the holy books of Lhasa monks.  His name is variously rendered: Alexander Csomo de Körös is also accepted.  He called himself a “Siculo-Magyar” and I thought that (like me) he was Sicilian and Hungarian, but, in fact, “Siculo” is a latization of Szekel, the hereditary guardians of the Hungarian frontier who claim direct descent from the remnants of the Huns. 

Portrait by August Schoefft
from surreptitious sketches

For over a hundred years, the life story of this obscure scholar was presented in a single biography by Theodore Duka, M.D., first written in 1885 and then reprinted in a limited edition of 1000 by Manjursi Publishing House of New Dehli in 1972.  Then in 2001, Short Books of Croyden, Surrey, came out with a new work by Edward Fox, much shorter, but obviously benefiting from resources liberated by the fall of communism.  Fox’s story illuminated details of Kőrösi Csoma’s depth of character. He was consistent, principled, and self-generating. He hoarded the cash coins in gold and silver which others invested with him for his travels and research, while he lived on figs and less.  Trekking with caravans, he had passed himself off successfully as “Sikander Beg” a Persian. 

Sandor Kőrösi Csoma believed that the homeland of the Hungarians was in the Himalaya Mountains.  The theory was widely asserted in his day.  The point is still in dispute.  By our best knowledge today, the Magyars are Finno-Ugritic people, cousins to the Samoyed, Ostyak, Vogul, and Finns of northwest Asia but “influenced” linguistically if not genetically, by Turkic peoples of central Asia.  The Hungarian word for “dog” is “kutya” and would be understood directly by the Ostyaks and Voguls.  The Hungarian word for “three” is “három” which obeys rules supporting the Finnish near-cognate “kolme.”  But in Hungarian, the vowels in a word all have the same pitch, as in Turkish.  For example, a noun becomes an adjective by adding “sag.”  The word for politically or legally free is “szabad”; and “liberty” is szabadsag.  But a nice word for your brother is “tesztver” and “fraternity” is “tesztvereseg”.  The deeper “a” becomes the higher “e” to maintain the consistency of sound within the word.

100-forint commemorative coin
celebrating the 200th anniversary
of the birth of Sandor Kőrösi Csoma.

But all that came after the lifetime of Sandor Kőrösi Csoma: 1784 to 1842.  In his time, Hungary was suffering under the Austrian crown for their revolts, especially that of Ferenc II Rákóczi from 1703 to 1711.  However, that struggle brought sympathy and support from England, evidenced by a trust of ₤11,000 raised and held by the Archbishop of Canterbury. Hungary always had a strong Protestant minority. Csoma’s primary and secondary education was at a Calvinist school where he eventually became a lecturer in poetry. So, Csoma found ready support from British consuls and merchants as he walked from Egypt to Persia, Afghanistan, and India.

Monastary at Zanskar
(Wikimedia Commons)

He was 35 years old when he left Bucharest on November 1, 1819.  He had studied and mastered languages all his life, including formal enrollment at the University of Göttingen to attend lectures in philology.  His letters to Captain C. P. Kennedy, assistant political agent at Subathú, summarizing his journey and explaining his intentions, were in English.

Csoma spent eighteen months with the abbot of Zangla in the Zanskar region of what is today the Indian state of Jammu and Kashmir in the Himalayas.  He compiled a 40,000-word dictionary and a grammar of Tibetan.  These he left with the Royal Asiatic Society at Calcutta before traveling back into the mountains where he died of a fever at Darjeeling.

ALSO ON NECESSARY FACTS
Sacred Silver from the Roof of the World
Financing a Revolution
My Grandmother and Science
Linguistics Debate: What Colors are Your Rainbow?

The Success of the WEIRD People

No single cause explains our standard of living.  From the Renaissance to the Enlightenment, the industrial revolution, and now the information age, the upward rise in standard of living is the material evidence of deeper attributes.  The aggregate of those beliefs – largely unstated and accepted as “normal” – does explain our success. 

“The Weirdest People in the World: How representative are experimental findings from American university students? What do we really know about human psychology?” by Joseph Henrich, Steven J. Heine, and Ara Norenzayan (all from the University of British Columbia Department of Psychology and  published in Behavioral and Brain Sciences, Vol33; 2-3 , June 2010, pp 61-83; available from the authors here) explains that we have

made ourselves – the Western, Educated, Industrialized, Rich, and Democratic people – the standard for “human nature.”  They say cogently that psychological experiments which supposedly tease out the basic patterns of “human nature” really tell us only about a small group: undergraduates in psychology departments, their friends, and sometimes their young children. The paper demonstrates that most people on Earth seem to hold entirely different views than we do.  And “views” is the basic problem.  What we accept as standard optical illusions work differently or not at all among different peoples around the world.  The paper is well worth the time to read through and mark up.

I found in their thesis the unintended corollary argument that our success is the result of those very attributes that set us apart from everyone else on Earth. 

The acronym WEIRD is nice, but does not place the elements in order.  Being educated first led to our becoming rich, and therefore democratic.  That this happened in “the west” (northwest Europe and the English colonies) is observable; but why here and not elsewhere may be an intractable problem.  The Renaissance started in Italy.  The Enlightenment was born in France.  How the Glorious Revolution of 1688 allowed James Watt’s steam engine to empower the middle class of America is complicated; but the facts are observable.

Start with education.  Other cultures have knowledge, even broad, deep, complicated, and consequential.  The difference is that ours is arguable.  It is important that charlatans such as Paul Feyerabend and Jacques Lacan be kept around to remind us of our limitations.  After all, their claims were rooted in the statements of real scientists who themselves explained that discovering deep truths did not come from following the recipe of the scientific method.  (See The Double Life of RNA by the Howard Hughes Medical Institute and PBS Nova about the work of Nobel laureate Thomas R. Cech.)  Insight and intuition nonetheless must be subjected specifically to that scientific method – and must be validated by independent testing.  We test our beliefs and abandon the ones that do not work.  It is not perfect or consistent; but in the main, culturally, our society operates by trial and error, argument and proof.

In her foundation essay, “Bourgeois Virtues,” (on her website here) Dierdre McCloskey pointed out that while the patrician Achilles was subjective and the peasant St. Francis was objective, the bourgeois Benjamin Frankin was conjective.  In other words: price is open to discussion.  She also noted that in commerce we do not convince (conquer), but rather, persuade (soften; sweeten).  That is different from the attitudes of other peoples. 

In the Ultimatum game, one party is given a largess with instructions to share whatever they want with the other party.  If the other party feels that the split is inequitable, no one gets anything.  In our society, most people draw the line at a 70-30 share.  If the recipient does not get at least 30%, then no deal.  Some other people are more rational in the pure market sense: any gain is better than nothing. Some other cultures feel that the distributor is under no obligation to share anything.  Some people (especially in Russia, Turkey, and Saudi Arabia) will engage in "altruistic punishment" where they would pay out from their own share without recompense to bring a loss to an unfair distributor. 

It is hard to say whether any of those is provably better.  But our willingness to accept a 70-30 split but deny an unfair cut explains much about how our democracy works: majority rule; minority rights.  

The fact that 90% of the world is not "individualistic” does explain why 90% of the world is poor.  But that is changing.  Global capitalism brings American (western) values to everyone.  Not every person in every place needs to adopt every aspect of our culture, but education, wealth, individualism, democracy seem to be mutually integrated.

Entrepreneurship

Writing over 300 newspaper and magazine articles about business, technology, and culture, I have interviewed very many entrepreneurs. Perhaps my personal favorite was "The Business of Musical Theater: The Dough behind the Do-Re-Mi" for the New Mexico Business Journal.  I have met all kinds of successful entrepreneurs and all kinds of not-so-successful. "All kinds" describes both the limitations and the potentials. In other words, there is no formula. The Austrian School of Economics has worried this problem for over 75 years. As the leading advocates for laissez faire capitalism, the Austrians have never agreed among themselves what entrepreneurship "is."

Part of the problem is that we were raised in schools to want short definitions that are easy to memorize, like Orwellian newspeak.  The very complexity of enterprise works against that.  The Concise Encyclopedia of Economics from the Online Library of Liberty offers this multi-faceted explanation:

“An entrepreneur is someone who organizes, manages, and assumes the risks of a business or enterprise. An entrepreneur is an agent of change. Entrepreneurship is the process of discovering new ways of combining resources.”  Entrepreneurs also increase the value of the resources under their control. “Schumpeter stressed the role of the entrepreneur as an innovator who implements change in an economy by introducing new goods or new methods of production. In the Schumpeterian view, the entrepreneur is a disruptive force in an economy.” (Read the entire article here.)

Peter Schumpeter, Israel Kirzner, and Frank Knight are among the Austrian school economists who have thought through entrepreneurship.  Of course, Ludwig von Mises and Friedrich A. Hayek also addressed it, but their focus was on other problems and their treatment of entrepreneurship was undeveloped. Even though they were passionate advocates for the open market, they did not study the differences between capitalism and enterprise, innovation and invention, market efficiency and marketing.  

“Kirzner's procedure is based on an analogy, or parallel, between what he calls the entrepreneurial element in individual decision-making and entrepreneurship in the market interaction…He isolates the entrepreneurial element by contrasting routine optimizing behavior with what he claims we can know about true individual action …  Individuals spontaneously discover means of satisfying their wants. … Another term he uses is alertness to hitherto undiscovered opportunities.”  This is not mere “economizing” but a deeper insight. “Third, he identifies what he regards as a crucial kind of action in a market economy -- arbitrage. He associates entrepreneurship in the market economy primarily with this action.” Arbitrage is the engine of efficient allocation. (See “Kirzner” by Prof. James Patrick Gunning, Feng Chia University, Taiwan, on Constitution dot Org here.)

 A more subtle approach is being pursued by Nicolai Foss, Peter Klein, and Mario Rizzo who follow Frank Knight and Ludwig von Mises on the entrepreneur’s judgment of uncertain future market conditions.  “Judgment is exercised in the act of investing in  and allocating resources to specific time-consuming production processes that are organized and controlled by the entrepreneur until the completion and sale of the product.  For Foss and Klein the entrepreneur is therefore a capitalist and owner.” (See “Klein Versus Kirzner” by Joseph Salerno on the “Bastiat”pages at Mises dot Org here.)

Traditional college classes in economics teach that markets move toward “equilibrium” that some magical point exists where supply meets demand at a price.  This is not mere observation, but an implicit worldview.  The goal is a static social world of sustainable predictability.  The Austrian school has a different weltanschauung.

Anousheh Ansari of the
X-Prize Foundation

 “I think it is highly useful to think in non-equilibrium terms, to be open to the possibility of change and surprise. You certainly cannot do good economics without understanding the role of surprise. But if one pursues this to the point where the surprises tend to overwhelm the regularities, then I don't believe you have a science that reflects existing realities. … Entrepreneurship is not always equilibrating. …  The idea I reject is this: there is successful entrepreneurship, there is unsuccessful entrepreneurship, and it's a toss-up which is going to outweigh which in the end. … The fundamental Misesian insight into human action is that it involves a tendency to be right rather than to be wrong. People have an interest in being right. …  This does not guarantee "equilibration always." And certainly a permanent equilibrium is out of the question. It would be incorrect even to imply that in any given time period, the changes we observe are necessarily equilibrating. But there are tendencies which tend to overwhelm disequilibrating forces in the market, most of the time.”(Austrian Economics Newsletter, Interview with Israel Kirzner, Spring 1997, Volume 17, Number 1 here.)  (See also "Supplies and Demands" here on Necessary Facts.)

  Moreover, traditional business management classes teach that the unremitting failures of inventors and early adopters prove that they are wrong.  Success, the B-schools claim, comes from following the wreckage to where the markets are now ready for a mature product or service.  Clearly, this is the rejection of entrepreneurship via “the fallacy of the stolen concept.”  You cannot follow failed market leaders to successful markets, unless such leaders exist in the first place. No one can follow unless someone goes first. 

The modern history of computing echoed much of the early history of railroading in America.  Failures and successes both combined to re-direct existing capital (whether trackage and rolling stock or software and hardware) and did so to attract ever larger investments.  (See The Man Who Found the Money: John Stewart Kennedy and the Financing of the Western Railroads by Saul Engelbourg and Leonard Bushkoff (Michigan State University Press, 1996).  In the days of railroading, the term “venture capitalist” would have sounded redundant. 

Felicia Day:
Acting as Entrepreneurship

In our day, entrepreneurs expect “angel funding.”  But angels are immaterial and eternal. Therefore, they cannot have human morality because they do not face the human need for survival.  The problem with angels is that not needing to eat, they do not know how to sow and plant.  They cannot even give good information because they have no basis for judgment.   If you have a bright idea and cannot find funding, then you are getting good information. 

If you think that you are smarter than everyone else – and you may well be – then you could have an entrepreneurial opportunity to disrupt a market, remove an inefficiency, and redirect resources by supplying an unmet need.  

ALSO ON NECESSARY FACTS
Venture Capital
Engines of Creation
Objective Intellectual Property Law
Open Secrets
The Genius of Design

KALLIOPE

Last night, on patrol, I met a Muse.  Kalliope, the muse of epic poetry passed by at 6th and Congress.  She was coming from 6th and San Jacinto where she had been performing.  

I thought that she was a student in the Classics department at UT even though she did not look a day over 2500, but she said that she is a working artist.  She said that it takes about three hours to put on her make-up and that she recites epic Greek poetry on the streets downtown during festivals.  

She handed me a slip of paper. "Q: What did Athena say to Medusa? ... A: I haven't seen you in Aegis."  I tossed some coins into her lekythos (no handles, so it was not an amphora) and said, "Ephkaristi" but then corrected myself and pronounced in the archaic "e-u-karisti" and bade her "Kalli nikti" (modern Macedonian accent, but that was how I learned it.)  

I have interviewed numismatists from Oxbridge who shared their experiences of having learned Greek from Homer and Thucydides then tried to take a taxicab or order dinner and found themselves like tourists in the UK attempting to communicate in Elizabethan English learned from Shakespeare. 

We learn a funny kind of ancient Greek anyway, "Erasmian" pronunciation from the English Renaissance.  For one thing, in discussing the atomic theory, Aristotle called S and D the "atoms" of Z.  So, we know that "one letter one sound" is not entirely correct.   The Phi we say like the fricative f.  However, the Romans brought the world "philosophia" into Latin, but they had the fricative F as in Flavius and Forum.  They wrote what they heard and it was not "filosofia" as in modern Italian.  Speak each sound separately: p-hilosop-hia." Concerning vowels, to keep the meter in poety, vowel pairs such as EU (Eutrope, Europa), must be spoken as glides, as if in English "ay-oo tro pay" and "ay-oo-ropa."  And the R is rolled: RHo.  The Y was our U: "Thucycides" should have two of them.   (For more, see Vox Graeca by W. Sidney Allen,  itself now a classic. )