# Technical writing help

1. Jan 2, 2012

### david90

I'm writing a report and I'm having trouble coming with the right words to describe a procedure.

Is there a better way to say "Before wiring PB2 (pushbutton) to the relay, refer to the wiring label on the relay to find the relay socket terminals function." ?

What I want to say is learn where the screws on the relay socket go to (coil, contacts etc) before wiring to it.

Last edited by a moderator: May 5, 2017
2. Jan 2, 2012

### sandy.bridge

Perhaps direct the reader to a set of schematics which will depict the function of each of the sockets?

3. Jan 2, 2012

### technician

May not be much help but I would say that, in a report or set of instructions, it is not good to say "BEFORE........"
I feel you should say what needs to be done in order !!!!
Imagine a cake recipe.... put 4 eggs in a bowl, add flour , add water, before you put the eggs in the bowl take them from their shells....that sort of thing.

4. Jan 2, 2012

### david90

The relay cube that can be inserted into the relay socket has a wiring label (kinda like a schematic) on it.

5. Jan 2, 2012

### AlephZero

I would say something like

Look at the wiring label on the relay and identify the .... and .... terminals. (You might want to add something about HOW to identify them, e.g. the relevant color codes, symbols, or whatever). Then wire PB2 to these terminals.

6. Jan 2, 2012

### sandy.bridge

Then I think it would be suffice to merely prompt the reader to analyze the physical device before attempting to wire it.

7. Jan 2, 2012

### Averagesupernova

As someone who has done technical writing for electronic assembly and sub-assembly I have to say that no matter how clear it is made some idiot will find a way to mis-interpret it. Assembly sheets would be distributed at the beginning of a production run and if there was something that was unclear to an assembler they would question me on it and I would explain it to them with some handwritten notes added. Then at the end of the run these sheets would be turned in. I would ask if there are ANY other things that they don't understand and should be made more clear. The answer was no so I made the handwritten notes permanent. What do you suppose happened the next production run? The SAME assembler couldn't understand a different part of the procedure. Hmmmm, last run it was crystal clear and now suddenly you don't get it? After 5 or 6 production runs less than a couple of months apart? I wanted this employee gone so bad.

8. Jan 2, 2012

### AlephZero

That works (sometimes!) for assembling flat-pack furniture, but not for anything that might be life-threatening. Not unless you want to get sued for damages, anyway.

9. Jan 2, 2012

### turbo

Technical writing is fraught with pitfalls. First, avoid writing in the passive voice. You will lose a lot of people that way.

My method was to write up a step-by-step procedure (in a list format), and then turn that into prose, with explanations for *why* things should be done in a certain order, including the repercussions for screwing it up. You can include a version of the list before or after the prose, but you really need to get descriptive above and beyond the list. All concerns about safety for the humans and equipment involved ought to be laid out up-front, so there is no room for gross errors. Good luck.

BTW, much of my technical writing was aimed at providing better documentation and system descriptions for the operators of Kraft chemical-recovery boilers in pulp mills. Those monsters generally operated at 600 psi to 900 psi and they could be pretty dangerous if feed-liquor fell out of acceptable solids-concentration parameters. I carried $1M in liability insurance just so I could write those manuals, though a disastrous boiler explosion would eat up the whole$1M in one shot.

10. Jan 3, 2012

### jim hardy

don't assume the reader will remember the pin-out long enough to wire it up.

if you wish , give him a list of functions of pins

but make your wiring directions one action per step -
eg "connect red wire AA to coil+ , which is terminal 2 ."
action first, location next
order of sentence above tells him he'll need a screwdriver in one hand and red wire AA in other, then directs his eye to where to put them.

little details like that make a procedure followable.