by Mark L. Levinson

In the premiere of The Why of Style, I considered a number of beginnings for a manual and decided on “telling the reader what the product is. ‘TiePlumb is a program that uses your computer’s camera and screen to help you gauge the straightness of your necktie.’”

Richard Mateosian wrote in to speak for the software-installing public:  “You’re telling me this?  How stupid do you think I am?  I paid $29.95 for a computer program without knowing what it does?”

Richard is right.  If the Kafka Memorial Bank of Prague distributed copies of TiePlumb to all its four hundred loan officers, then such an explanation might be helpful to those who aren’t sure what they’re getting.  But if TiePlumb is sold to individual consumers, then reading that sentence is a little like answering a knock on the door and finding a man there who says, “Hello.  I’m the man who knocked on your door.”

Granted, writing needs to acknowledge the known, at least tacitly, in order to stably introduce the unknown.  But still, every sentence — even the first one — should add informational value if possible.  A technical writer might take a hint from Julius Caesar, who instead of starting his book with “This is the story of my campaign in Gaul,” started with “The entirety of Gaul is divided into three parts.”  You could write “TiePlumb works on bow ties, string ties, and four-in-hands.”  Or whatever the product-specific equivalent is for you.

Once you’ve managed not to be devoured by the Lion of the Overobvious that crouches at all beginnings, there are the lizards of the overobvious that insolently sun themselves in small empty spaces where you have nothing at all to write.  You’re working your way through a data-entry window, explaining it field by field — field name on the left, explanation on the right — and you come to a field labelled “Necktie’s brand.” 

You type, “Necktie’s brand — The brand of the necktie.”  You start backspacing.  The lizard lies down in the vacancy and looks at you.  You look at the lizard.  Is there anything less than idiotically obvious that you can add to “Necktie’s brand”? 

You could mention that the maximum length is 255 characters.  Or that the field is not case-sensitive.  Or that it’s optional, or that spaces are allowed.  But unless you can find some such property that is particularly relevant to the necktie’s brand in a way that it isn’t relevant to every other field, then in order to justify including it for the one field, you’ll need to include it for all the others — even where, by doing so, you may be dulling important information with a coat of supplementary trivia.

If you have the freedom, try to avoid a format that so strictly forbids explanationlessness.  If your documentation is on line, you might consider a format in which the field name expands to include the explanation when clicked.  Then “Necktie’s brand” would simply not be clickable and not look clickable.

Or on paper, you could arrange the explanations around a picture of the window, with a call-out line linking each field to its explanation.  And “Necktie’s brand” would simply not have a call-out line and not have an explanation.

In Hebrew you can say, in a single word, “according to its own phrasing,” which I suppose might suitably serve as an indication saying “it’s all in the field’s label” when you don’t have the option of saying nothing at all.  What would the equivalent be in English?  “Self-explanatory” is a little insulting to the reader.  “As labelled”?  Perhaps a readership could learn to accept that. 

As always, comments and questions are welcome: