×
INTELLIGENT WORK FORUMS
FOR ENGINEERING PROFESSIONALS

Log In

Come Join Us!

Are you an
Engineering professional?
Join Eng-Tips Forums!
  • Talk With Other Members
  • Be Notified Of Responses
    To Your Posts
  • Keyword Search
  • One-Click Access To Your
    Favorite Forums
  • Automated Signatures
    On Your Posts
  • Best Of All, It's Free!
  • Students Click Here

*Eng-Tips's functionality depends on members receiving e-mail. By joining you are opting in to receive e-mail.

Posting Guidelines

Promoting, selling, recruiting, coursework and thesis posting is forbidden.

Students Click Here

Jobs

Instruction Writing
2

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?

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 heartily agree.  Instructions such as yours are effectively requirements specifications.  As such, the criteria for success must be quantifiable and observable.  Since "proper filling" can only be proven by the demonstration of correct level, your original instruction is correct.  The user can immediately determine that he/she has correctly implemented the instruction.

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

Really good manuals involve a number of question and answer sessions between the engineers and the manual writers.  Engineers in general are poor manual writers because we tend to assume that the reader is familiar with the equipment.  The tech writers generally have no knowledge of the equipment, and hence should interview the engineers.

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 too agree. "Ensure the hydraulic reservoir is filled to the proper level" is not the same as "Ensure hydraulic reservoir is properly filled."  Further, the second statement begs the question, "What is the proper method for filling the reservoir?"

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

I pretty much agree with what has been said so far, but would add, that proof reading (and testing for comprehension) by potential users might be in order.

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

(OP)
The main point I wanted to get across was that as far as technical writting goes, there is no longer a need to avoid "and" and "the" to be concise.  Or am I way off base?  Or do you still sacrifice good grammar for tech-speak?

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

MadMango,

   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

In my opinion technical writing MUST be precise, and SHOULD be concise. Leaving out words like "and" and "the" can certainly create confusion, therefore they should be left in if in doubt

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

MadMango,
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

MadMango - I don't think you're off base at all.  I don't think you should ever sacrifice sacrifice good grammar for techno-speak.

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

From the legal point of view, a company lawyer might prefer "Ensure that the hydraulic reservoir is properly filled", specifically because  it is so vague and places most of the responsibility on the user. But I'm not saying that I prefer it.

RE: Instruction Writing

...but

"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

inschunier?

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

Yes, e-pete. We inscuhniers are not any good at spelling

RE: Instruction Writing

Hmmm.
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

ok, I think I get the idea "inscuhniers" is supposed to be a misspelling of engineers.

How does "sc" equate to a "g" sound?

=====================================
Eng-tips forums: The best place on the web for engineering discussions.

RE: Instruction Writing

Once upon a time I could quickly scan my workshop manual and then proceed to dismantle my car engine without hardly referring to it again (and I was only 15 then).

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

e-pete,

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

No need to apologize for being funny.  I was just a little slow to catch onto the joke.  My wife hates it when I ask her to explain jokes.

=====================================
Eng-tips forums: The best place on the web for engineering discussions.

RE: Instruction Writing

Hi there. I am currently working on creating some "work instructions" for our assembly area at our factory. I was originally going to just type these out and maybe copy and paste some digital pictures next to the appropriate step. Then, one of my colleagues had mentioned the possibility of using a software package that creates work instructions in an "easy-to-read" format without much thought by the guy writing down the steps, me. I was unsure if any of you had used software for writing instructions like this or if you knew of any good packages yourself? I would really appreciate some feedback on what works/worked for you all. I have basically only heard of one brand, Talsico, but I am sure there are others...right? Thanks in advance.
Signed,
Zack

RE: Instruction Writing

KiwiKid,
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

boltonza,
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

Hi jmw,

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!

Red Flag This Post

Please let us know here why this post is inappropriate. Reasons such as off-topic, duplicates, flames, illegal, vulgar, or students posting their homework.

Red Flag Submitted

Thank you for helping keep Eng-Tips Forums free from inappropriate posts.
The Eng-Tips staff will check this out and take appropriate action.

Reply To This Thread

Posting in the Eng-Tips forums is a member-only feature.

Click Here to join Eng-Tips and talk with other members!


Resources