Commentary: What Technical Writers Must Learn from the History of Programming

Abstract

Complicated documents often affect readers the way computer programs affect computers; technical writers are prone to many of the same serious errors that plague programmers. Among the many principles that writers can learn from programming are: 1) Models save money: it is far more economical to develop detailed outlines and mockups than to improvise from a vague outline. 2) Quality demands maintainability: every complicated document will need frequent revision, and only documents designed for ease of change will be kept current. 3) The trouble is in the interfaces: the procedures and tasks in a manual are not as error-prone as the rules for moving from part to part of the book itself. 4) Readers are subject to the laws of physics: many publication economies produce documents that defy the physical powers of the reader. 5) Communication is control: readers must be prevented from getting lost.