(Click for larger drawing)
 "........ and if U5 goes high, then U6 goes low, provided that U3 is already low. But if U3 is high, then U6 and U10 go low unless U5 is low, - in which case U6 stays high."

"Words, words, words.
I need a good map!"

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

1. Unsystematic layout should not be used
The diagram below needs a lot of explanation, because voltage dividers are not drawn as voltage dividers, feedback paths are not recognized, etc. Without a travel description you would be lost.


2. Use instead a functional layout
For the repairman the diagram above is almost self-explanatory. The highway code of this diagram is simple:
1. Name the electrical functions, and mark them with dotted lines around them.
2. Indicate the main signal paths with a thick line. Signal paths from one function block to another should not pass through a third function block.
3. Let the main signal paths go as straight across the diagram as possible.

 

 

 

 

 

 

 

J. TECHNICAL WRITING AND COMMUNICATION, Vol. 12(2), 1982

WHY ARE TODAY'S TECHNICAL DESCRIPTIONS STILL "A JOURNEY THROUGH THE UNKNOWN?"

SIGMUND TVEITO
Technical Descriptions Department, A/S Elektrisk Bureau, Norway

ABSTRACT

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?

THE PROBLEM

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
More than a century ago, the great explorer Stanley Ignall crossed the narrow pass of Coax, and forced his way through the jungle of Piloreceevaland. The intrepid traveller's journey had taken him along numerous rivers and many half-hidden paths in this previously undiscovered and unexplored country.

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:
  In front of me the mountain lay
Tremendous peaks beneath a sky so blue
I longed to climb it, this very day.
I marked it in my sketch as U.


"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:
  S. Ignall thereafter forced his way into Piloreceevaland via the Pass of Coax, and did not rest until he reached mountain U.


And here is something taken from a typical 1980s service manual for electronic equipment:
  The signal is applied to the Pilot Receiver via Coaxial Contact 33, and is routed herefrom to Converter U.
It could nearly be called plagiarism!

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).
The communicator is then supposed to decode the engineer's message and produce a service manual which should contain no more and no less than what a repairman needs to repair the equipment. It's now wonder poor Olav was in despair.

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.
The communicator is therefore frequently tempted to do two things:

1. Make the maze more beautiful by using straight lines and standardized symbols.
2. Use the R&D engineer's outpourings verbatim, checking the grammar and the spelling, of course, and adding some more "travel instructions" (giving the communicator the illusion of having at least improved the input somewhat).

The end result is a be-yoo-ti-ful, low-quality minimum-usefulness service manual.

MAPS

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)