J. TECHNICAL WRITING AND COMMUNICATION, Vol. 12(2), 1982
WHY ARE TODAY'S TECHNICAL DESCRIPTIONS STILL "A JOURNEY THROUGH THE UNKNOWN?"
In order to repair defective equipment in the shortest possible time, the repairman needs functional service manuals. These manuals are made by the technical communicator, who gets his "input" from the development engineer. Three different people, with different background and training.
This article concentrates upon the relationship between the engineer and the communicator. How can they help each other in order to obtain a useful manual?
My colleague Olav is a technical communicator. As a new man in the department some years ago, he was working on a service manual for one of our products. Of course, he had problems (who hasn't?). He knew his style was not perfect, but that could be improved; so too could the readability level. His main problem was not, however, his output- it was his input, the basic information he needed to make the product understandable to the technician who was going to have to read and consult the manual in order to do his job properly.
Olav complained: "The development engineer and I just don't seem to speak the same sort of language when it comes to describing this product, and I really can't understand his diagrams. And out there somewhere is a customer waiting for a good service manual at a reasonable price. What am I going to do?"
To cheer Olav up, I told him a story:
Stanley Ignall, the great explorer
As he travelled, Stanley Ignall made countless notes and small
sketches. Once back in civilization, he assembled these notes
and sketches in a book, which he published under the title "An
Account of S. Ignall's Journey to Piloreceevaland".
The language, as was usual for those times, was flowery
and full of long, rambling, complicated descriptions, and the
odd bit of poetry:
"Now," I said to Olav, as I showed him my precious first edition of Ignall's book, "does this remind you of anything?"
"Yes," he said, "it looks just like the stuff I get in from the development engineers whenever I ask for input for a technical description or service manual."
"Precisely," I said. "It looks as though Ignall's books still have their readers. Engineers and especially development engineers are very future-oriented, but sometimes, just sometimes, they appear to live in the past. Today's ambulance driver, or today's fire engine squad needs to travel fast on the way to an emergency. They can't waste time trying to make their way by following an Ignall guide; they need good modern maps and signposts. And so do our product installers, maintainers and repairmen."
Mind you, it not only our own development engineers who are fond of S. Ignall and his works. I've noticed the same tendency among some technical writers, too (but not our Olav of course). Look at what I mean. First, here is a sample from S. Ignall:
And here is something taken from a typical 1980s service manual for electronic equipment:
INPUT AND OUTPUT
Why do development engineers and technical writers still use the old jungle explorer's writing method? Is it done deliberately, or is it due to some kind of indoctrination? Has no one ever told them about the new way of doing things?
Let's have a closer look at a situation familiar to many of us in the technical communications business.
Here's a technical writer, or better still, a "technical
communicator". He's getting his input from a research and
development engineer (who, like most R&D engineers, prefers
to explain his thoughts without the use of paper).
A Dangerous Temptation
Since the communicator's input so often seems to be of the
Stanley Ignall type, a collection of notes and vague sketches,
resembling mazes more than maps, with no signposts, it's not
easy for him to make a good, clear readable map out of the mess.
After all, he hasn't actually been in the jungle himself, unlike
Mr. Ignall or the R&D engineer.
1. Make the maze more beautiful by using straight lines and
The end result is a be-yoo-ti-ful, low-quality minimum-usefulness service manual.
Demand Good Sketch Maps
Well, if you find yourself in a situation like that, you've got to do something. The first step might be to improve the relationship between the communicator and the R&D engineer.
It's no use simply ordering the engineer to provide us with better drafts. Ten to one, he'll come up with answers like "That's not my job, that's yours!" or "I haven't time for that sort of thing. I'm supposed to be developing new products". We'll have to find better ways than that to improve our relationship.
Why not start by teaching our engineers a few points about good maps? Provided the rules are simple and short, he will appreciate our help. After all, we'll be making it easier for him, too. Whatever you do, don't try to give him three volumes on "How to make technical descriptions". Most likely, he'll throw them at you.
A Good Map is Worth a Thousand Words
Here's a simple example of the kind of thing I'm talking about. After hearing Olav's lament, in my early days as manager of the Technical Descriptions Department, I designed a "diagram of good practice, for analog circuits" on an A4 sheet of paper. Our drawing office now uses it to check the R&D engineers' circuit diagrams. If the draft is not made by the R&D man in accordance with these simple rules, we simply do not accept it.
The example (left column) shows two different ways of drawing the same circuit diagram ("post Ignall" and "post Olav"!). If you're having problems of the kind outlined above, it might be worth your while to devise your own "post-Olav" map, and try it out on your R&D engineer.
The Ultimate Map
Technology progresses. Digital circuits, microprocessors, and software are steps along the road to the future.
Ignall's descriptive method is obsolete today. Today's methods may be obsolete tomorrow. As circuit development advances, new and better information methods must also be developed.
The ultimate map may never be found. But one thing is certain: Tomorrow's serviceman will have to travel fast. It's our job to give him a more efficient guide than the old jungle explorer's diary. And we can do that by helping the R&D engineer make better maps. Which in turn will help us, the Olavs of this world, to do a better job overall.
(A joint venture job with Nora C. Nordan, who invented my colleague Olav)