Written by Mark L. Levinson

Across the ocean thousands of years ago, the Mayan civilization had wheels but never exploited them for transport.  Do you know why?  Because they didn’t read the manual.

Do you know who said “Nobody reads the manual anyway”?

Kallinikos of Heliopolis, when they asked him to provide the exact instructions for making Greek fire, said “Nobody reads the manual anyway.”

Antonio Stradivari, when they asked him to jot down exactly how he crafted the violins, said “Nobody reads the manual anyway.”

Asmodeus the demon, when Solomon wanted to record for posterity exactly how the stones of the Temple were floated into place, said “Nobody reads the manual anyway.”

The sculptors of Easter Island, the boulder schleppers of Stonehenge, Nijinsky when they asked him to document his choreography, they all said, “If anyone has any questions, they’ll phone us.  Nobody reads the manual anyway.”

But enough of the Red Buttons routine.  The point is to think what might happen in the future.  And I’m not talking about puzzled scholars in the year 6000 wondering what kind of a tube was a YouTube.  I’m talking about the customers of your product’s next version.

First of all, how do they even know it’s the next version?  If the product has a GUI, is the version number right there on the screen with the product name, or does the user who wants to report a problem need first to solve the additional problem of where in the menu system the version number is?  If the product has a printed manual, is the version number right there on the cover?  Or does the reader need to open the book in order to find out whether it was worth opening or obsolete?

And by the way, when the reader has opened up that book, is the writer’s name inside, somewhere among the copyrights and disclaimers?  Back when I worked at Daisy Systems, the lawyers axed our writer credits from the books.  The lawyers were worried about what happens in the future, when a writer leaves the company.  The company could be called deceptive if it left the writer’s name on the book, because the company can no longer truthfully boast the writer’s presence.  But the company could be called deceptive if it took the writer’s name off, because the book is still the writer’s work.  Either way, the writer could sue the company. 

Even without the problem of former employees, a problem of present employees can easily arise from the question of who gets top billing when Shmulik documents version 1 and Srulik writes the revision for 1.5.

As for the content of the documentation, the point is to think what might happen in the future — and then shut up about it.  When the product has a drawback, and you know that a solution is on schedule for the next version, you can be tempted to break the news:  “Note:  If you have a beard, you may find that the TiePlumb necktie straightness gauge treats your beard as if it were part of your necktie.  This problem will be solved in the next TiePlumb release.”  Such glad revelations are a temptation that should be resisted.  Assurance that the problem is known and being worked on may be welcome, but it should come without any indication of when the problem will be solved. 

For one thing, the longer your company seems to have known about the problem, and the more firm and confident your company seems about the solution, the more the reader will resent the company for not simply solving the problem instead of reporting it. 

Second, if the marketplace hears that a significant problem will be solved soon, they won’t rush to buy the version with the problem.  They’ll wait for the version with the solution. 

And third, anything could happen.  Maybe the problem is much harder than anyone thinks.  Maybe the solution won’t be in the next version because sudden, unrelated customer demands will result in a new version sooner than anyone dreams.  Maybe the company will be bought out and the new owners won’t care about the problem. 

So while we may not be writing for the ages, it’s important to remember we’re writing for the next couple of years and whatever we write must stand up to an uncertain future.  Unless, of course, your users are modern Mayans and nobody reads the manual anyway.

Comments and questions are welcome:

Help your colleagues - participate in the Salary Survey!