Instruction Writing
Instruction Writing
(OP)
I work in a product development environment, and many times I am tasked with writing operational and maintenance instructions for new products. I keep getting complaints that my instructions are "too novelist" and I have to be less "proper" and more "technical" in my approach.
The biggest suggestion I get is to lessen the use of words such as "and" and "the". Here's a quick example:
"Ensure the hydraulic reservoir is filled to the proper level."
It has been edited by my Tech Pubs department to read:
"Ensure hydraulic reservoir is properly filled."
To me the edited version comes no where close to what I was instructing. There's a big difference between filling something to a proper level, and properly filling something.
I can understand the need for precise and economical use of the written word to convey meaning in instructions. I could understand the point more if we didn't work in a world with word processors and computers. I think the days of white out and ditto machines are behind us. Am I the only one that thinks this way?
The biggest suggestion I get is to lessen the use of words such as "and" and "the". Here's a quick example:
"Ensure the hydraulic reservoir is filled to the proper level."
It has been edited by my Tech Pubs department to read:
"Ensure hydraulic reservoir is properly filled."
To me the edited version comes no where close to what I was instructing. There's a big difference between filling something to a proper level, and properly filling something.
I can understand the need for precise and economical use of the written word to convey meaning in instructions. I could understand the point more if we didn't work in a world with word processors and computers. I think the days of white out and ditto machines are behind us. Am I the only one that thinks this way?
Ray Reynolds
"There is no reason anyone would want a computer in their home."
Ken Olson, president, chairman and founder of Digital Equipment Corp., 1977
Have you read FAQ731-376 to make the best use of Eng-Tips Forums?





RE: Instruction Writing
Stand your ground. Tech pubbies are good at English, but not good at engineering, otherwise, they'd be engineers. What they suggested may be good English, but lousy Engineering instructions.
TTFN
RE: Instruction Writing
In your example case you wrote:
"Ensure the hydraulic reservoir is filled to the proper level."
I could fill the reservoir with 7-up to the proper level. Would that be acceptable?
The writers came back with:
"Ensure hydraulic reservoir is properly filled."
This is too, general; it begs many questions, such as:
What is the proper fluid to put in the reservoir? Would different fluids be recommended for different environmental conditions?
Are there any special handling or safety precautions that must be observed?
What is the correct level? Do you have to measure, or is there a sight-glass or dip stick?
And probably many more.
RE: Instruction Writing
I find your original wording to be considerable better, as it makes it clear the intention of this instruction is to ensure the proper amount of fluid is in the reservoir, without regards to how it got there.
I line up behind IRstuff - Stand your ground.
RE: Instruction Writing
As an example, back in the late 80s, I had my first PC. The instruction manuals were obviously written by experts as they made extensive use of jargon, and presumed knowledge that a "normal" user would not have. For example, an instruction to "hit the return key" I was supposed to just know by instinct that the return key was actually labelled enter.
The books in the series "XXX For Dummies" has gone a long way toward rectifying this defect in software instruction manuals.
Regards
pat pprimmer@acay.com.au
eng-tips, by professional engineers for professional engineers
Please see FAQ731-376 for tips on how to make the best use of Eng-Tips Fora.
RE: Instruction Writing
Ray Reynolds
"There is no reason anyone would want a computer in their home."
Ken Olson, president, chairman and founder of Digital Equipment Corp., 1977
Have you read FAQ731-376 to make the best use of Eng-Tips Forums?
RE: Instruction Writing
I see two issues with your changed text. As you noted, they deleted a lot of secondary words from the text. Also, they made a change in your syntax, changing the meaning of your sentence.
Back in my drafting board days, I deleted "the" and "a" whenever I could. I replaced "and" with "&". This reduced writer's cramp. You have to press hard with a pencil so that things blueprint properly.
A long time ago, I took typing in high school. This has made my transition to computers way easier. My inclination on drawings is to write notes out in full. These notes do look a little weird to me.
Most people working on CAD are hunt and peck typists. You have to have some consideration for this.
Incidentally, I am not looking forward to voice recognition software. An office full of people arguing with their computers sounds scary to me.
As for ths second point, I agree with the other comments here.
JHG
RE: Instruction Writing
Regards
pat pprimmer@acay.com.au
eng-tips, by professional engineers for professional engineers
Please see FAQ731-376 for tips on how to make the best use of Eng-Tips Fora.
RE: Instruction Writing
I am guilty of typically using too may words to get the point across verbally and in writing so am sensitive to the correction which was suggested to you.
I personally like your original version but if breifness helps e.g. maybe the text on the label could be made larger given a briefer statement or some other good reason then the suggested change is OK if like IRstuff said it included the level thing.
IRstuff,
"...are effectively requirements specifications."
Am I missing something here? Is this grammatically correct? I have no idea what yuo are getting at.
Jesus is THE life,
Leonard
RE: Instruction Writing
As a compromise, you could offer the following:
"Ensure hydraulic reservoir is filled to proper level."
While eliminating a couple of words, I think it retains the original intention. To me, the intention should come first, not conciseness.
RE: Instruction Writing
RE: Instruction Writing
"Ensure that the hydraulic reservoir is properly filled" is the better alternative if it is in a check-list.
The procedure (how to fill it, with what to fill it and special considerations) should be detailed somewhere else in the manual.
But if this is the only place where the filling of the reservoir is mentioned, then a little more words should be used - like the original wording.
Don't take my words for it, though. I'm only a dumb inschunier - not even with English as my native tongue.
RE: Instruction Writing
By the way. I leave out my "ands" "the's" a lot. Sometimes leave out my subject. Just goes faster. Doesn't mean it's good though.
=====================================
Eng-tips forums: The best place on the web for engineering discussions.
RE: Instruction Writing
RE: Instruction Writing
A manual is no less a product than the product itself. As such it has to fulfill a number of different objectives and like a product there are often necessary compromises.
If the publications department make a change the simplest thing is to ask why. They may have perfectly valid reasons.
One suggestion made is the legal implications.
I can suggest that when the overall objectives are considered, readability in English is only one.
Readability of the translated versions is equally important. Since it will not be an engineer such as yourself writing the translations but a technical translator the impact of your choice of words must be considered as it affects translations.
In some cases the substitution may be because there pre-exists that phrase with a proven effective translation.
RE: Instruction Writing
How does "sc" equate to a "g" sound?
=====================================
Eng-tips forums: The best place on the web for engineering discussions.
RE: Instruction Writing
Now I lift the bonnet and think, forget the mechanical engineering, I'm going to need a degree in IT and electronics. The manual now takes longer to read than War & Peace. :-(
RE: Instruction Writing
Sorry. We are not only bad spellers. We are bad typers as well. The "sc" should have been "sch". I regret that I tried to be funny. It is very dangerous and backfiring is common.
RE: Instruction Writing
=====================================
Eng-tips forums: The best place on the web for engineering discussions.
RE: Instruction Writing
Signed,
Zack
RE: Instruction Writing
i take your point about car manuals, every time i go to do anything I have to craete an organisational table so that i can sequence everything. Why? because the Haynes manual says: "Remove the gearbox" (10.83) and when i get there it says "remove the exhaust system" page 16.1 or someothing.
A nightmare. It would be OK in multi-media but its a lousy way to write a paper manual.
JMW
www.viscoanalyser.com
Eng-Tips: Pro bono publico, by engineers, for engineers.
Please see FAQ731-376 for tips on how to make the best use of Eng-Tips Fora.
RE: Instruction Writing
You'd probably be better off starting a new thread. I think that "automated tech writing software" will definately stir up some spirited discussion.
David
RE: Instruction Writing
The more recent Haynes manuals contain far too many comments on the lines of 'refer to main dealer' and so on. Like WTF did I buy the Haynes manual? To tell me to go to a dealer? Nowhere near as good as they once were.
------------------------------
If we learn from our mistakes,
I'm getting a great education!