Latest posts by techwriter (see all)
- Test Your Knowledge of 4 Basic Fonts – Drag & Drop - January 27, 2017
- How NOT to Design a Web Site - January 25, 2017
- Hazards of Poorly Written Technical Documentation - December 26, 2016
By Steve Williams
As a technical writer, you strive for Accuracy, Clarity and Readability. But where do you strike the balance? Although the definition of Substance ought not to change, it is influenced by evolving trends in Style.
Substance is, of course, ever the more important part of technical writing. But Style is what keeps the reader awake!
Substance, here, includes Accuracy and Clarity.
Style, here, means smooth, interesting, intelligible — all of which can be lumped in under Readability.
Accuracy no longer has to mean mind-numbingly detailed writing. Clarity, in fact, proscribes that. Readability ensures that the technical information actually gets read. If no one is able to plow through a piece of technical writing, then the information simply does not get out.
No tragedy with an article such as this. But suppose a bridge building crew tossed aside a technical bulletin because it was unreadable. What if the loss of that information caused a locomotive to fall into a ravine, killing hundreds of passengers?
(Of course, one resulting headline pun might read: “Hundreds Die With Style.” But you, as a technical writer, would not be writing that one.)
All writing styles evolve over time; technical writing is no exception. Suppose we look at one short piece of an imagined technical article written in what would be an acceptable style in the early 1950s, then in the style of the 1980s and again in what some fear could become the style of the 2010s.
All three styles are describing a right triangle.
Technical Writing Style, circa 1950
The reader will be well acquainted with the fact that the length of the hypotenuse of a right triangle is defined by the square root of the summed squares of the other two sides. This quadratic relationship proves that the hypotenuse must always be longer than either the base or the altitude. The length of the hypotenuse can never be as long as the sum of the lengths of both the base and the altitude. These relationships are clearly seen in the following formula:
c-squared = a-squared + b-squared, where:
- c = the length of the hypotenuse
- a = the length of one leg (the altitude)
- b = the length of the other leg (the base)
A right triangle is defined as a triangle where the two legs, or sides, representing the altitude (a) and the base (b) meet at precisely 90°.
(This style was dull, but still much improved from technical writing of only a decade or so earlier. Requirements imposed by World War II had abruptly changed attitudes. Information had to be accurate. As well, it needed to be clear. Lives often relied on information being understood easily by hastily trained military technicians. But style was still very much a step-child in the technical writing of the 1940s and 1950s.)
Technical Writing Style circa 1980
The length of the hypotenuse of a right triangle (c) is always longer than the length of the altitude (a) or the base (b). However, the length of the hypotenuse (c) will not be as long as the sum of the lengths of the other two sides (a + b).
The quadratic relationships of the lengths of the three sides of a right triangle can be seen from:
c-squared = a-squared + b-squared
Right triangles are formed when the two shorter sides (a) and (b) meet at exactly 90 degrees.
(Technical writers were rapidly adopting a crisper style as trade and technology were now international business concerns. Clarity was catching up with Accuracy. You could no longer assume that your customers were native English speakers. As well, ordinary people started buying personal computers and were becoming interested in learning about technology. Readability was increasingly important.)
Technical Writing Style circa 2010(?)
The longest side (hypotenuse) of any right triangle is always longer than either of the other two sides, but interestingly enough, never as long as both short sides added together.
The right angle was used by ancient Egyptians to square up their buildings. They knew that if one wall was 30 cubits long and the other wall was 40 cubits, a string stretched kitty-corner across the room should measure exactly 50 cubits. If not, the corners would not be square.
In a right triangle the two shortest sides meet at a right angle.
See a Flash Animation of the famous Pythagorean Theorem at:
(Assuming that the blog and the sound byte push Style to the forefront, Short, Simple and Silly will then prevail. Although this third “article” is more or less Accurate and Clearly written, where is the Substance? In place, it misuses Readability in the form of human interest and historical perspective. It may well entertain, but as technical writing, it is feckless. It could also be misleading. Note the “any right triangle”; have they discovered other right angles that are not precisely 90 degrees?)
Good technical writing should consist of genuine Substance conveyed in an appropriate Style. It should deliver specialized information suitable for furthering knowledge or awareness within a targeted interest group. The function of technical writing is still to imprint, not to impress.
Steve Williams is a former technologist and technical writer. Retired now, Steve edits a noncommercial website: [http://www.writing4seniors.org]