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