×
INTELLIGENT WORK FORUMS
FOR ENGINEERING PROFESSIONALS

Contact US

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!

*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

More complicated than necessary?
4

More complicated than necessary?

More complicated than necessary?

(OP)
I'm in the process of writing a technical document. My manager to use a similar document for another project as the basis to get me started. As I was reading it, a couple of things ran through my mind:

1. why state the obvious? Anyone who is reading it isn't an idiot (or at least not THAT stupid...)

eg. The water in the tank corresponds to the amount of water in the system, and any significant changes to the water level is indicative of a potential leak in the system.

2. why use complex wording? Many of our clients speak other first languages. Doing this isn't going to help them understand (unless that was the point... quite devious indeed)

eg. ... will be accommodated by the inclusion of...
Why not just use "... will include..."?

Or is the point of all this to make the writer sound smarter than he/she really is and to make the company look like it knows what it's doing?

RE: More complicated than necessary?

2
Often such convoluted, long explanations are necessary to prevent an interpretation other than that intended; other times people just get carried away and forget when to stop.
What may be obvious to some might not be obvious to others not as familiar with the subject matter.  While there will always be better idiots, that fact does not negate the need to attempt to idiot-proof.
 

"Good to know you got shoes to wear when you find the floor." - Robert Hunter
 

RE: More complicated than necessary?

1. why state the obvious?...

Quote:

eg. The water in the tank corresponds to the amount of water in the system, and any significant changes to the water level is indicative of a potential leak in the system.
Another system may draw water from the tank during it's working cycle, and return the water upon completion. Your example, confirms that is not the case for the system in question.

2. why  use complex wording?...

Quote:

eg. ... will be accommodated by the inclusion of...
That statement suggests that an action is being made possible only because something is being included.

RE: More complicated than necessary?

I'll side with the suggestion that sometimes apparently superfluous detail is necessary to be explicitly clear on the intended meaning.

You know what it's meant to mean, so putting a brief phrase may work, however for someone not familiar with the subject it may not be explicitly clear.

Another factor may be active V passive voice.

Then there's the problem of a$$holes like me who often over think  instructions to see if there's any way it could mean something else, or it excludes something it should include...

Posting guidelines FAQ731-376: Eng-Tips.com Forum Policies http://eng-tips.com/market.cfm? (probably not aimed specifically at you)
What is Engineering anyway: FAQ1088-1484: In layman terms, what is "engineering"?

RE: More complicated than necessary?

"Technical document" covers a lot of potential ground.  Depending on the expected users of the document and their possible level of background, things that are very basic to the one writing the document may need to be spelled out explicitly.  This is especially true when the document will have to be translated.  

Simplifying details, as in your second example, can often lose nuance.  Whether this is important or not depends on the situation, and I at least can't tell you whether your situation is one where it matters or not.

But the answer that is both easiest & most appropriate to your specific situation:  ask the manager that gave you the reference document.  He chose it for a reason (maybe a good reason, maybe a bad one) and he knows what your under-construction document needs to acheive better than any of us here will ever know.

RE: More complicated than necessary?

2
A well-written and properly worded technical document should state exactly what is required to state, no more and no less; recalling that what may be obvious to you is not necessarily obvious to the reader.  Everything should be stated clearly, concisely and unambiguously, using the least complicated lexicon and most straight-forward constructs of grammar.  Colloquialisms, jargon, abbreviations, acronyms and other such stuff are to be avoided. Short sentences and paragraphs, logically arranged and easily referenced significantly improved clarity and readability by introducing ample white space and giving the reader a place to rest between concepts.  Excessively long paragraphs, made up of run-on sentences using language overtly designed and intended largely to showcase the writer's command of the language at hand - English in this case - should be avoided; also, refrain from unneeded use of other than the most basic of punctuation marks, i.e. the period (.), comma (.) and perhaps the occasional colon (:) or semi-colon (;) - recalling that many people find hyphens to be pretentious, and besides, most people don't really use the correctly anyway.  Note also that putting many things in parentheses (parenthetical offset) is annoying and difficult to read.  Often one (1) or more people will advocate for including numbers both numerically and spelled out.  In summary, short, concise, to-the-point writing - void of unnecessary embellishment - (either grammatical or prosaic) - and using the minimum of correctly applied punctuation is the least obfuscory vehicle for making one's point.

RE: More complicated than necessary?

There's a reason that some of us are paid to be technical communicators.
In fact, the somewhat densely-written message above mentions a number of them.
Audience analysis is key.
You have to understand the reader's needs (in this limited situation, not their life problems) so you can tailor the info to their level.
You can also have supplemental info in an appendix or supplement.

Note that MintJulep's message above needs a lot of formatting and opening up to make it look like a readable tech document.

Use Explicit and implicit structure -
Proper use of logical structure and headings, white space, bullets, numbering for steps, etc. all make a huge difference in usability.
Regards
Jay

Jay Maechtlen
http://www.laserpubs.com/techcomm

RE: More complicated than necessary?

This morning I was reading the label of a can on the conference room table during a meeting. It said, "This product was packaged in a facilility that processes peanuts". It was a can of peanuts.

RE: More complicated than necessary?

Mint.
Excellent example!!!

RE: More complicated than necessary?

As far as "complex wording" and translations go, usually taking the long route for sentence structure will translate better.

I catch myself modifying sentence structure when sending technical emails to coworkers or customers who are fluent in English, but it is clearly not their first language.


eg. ... will be accommodated by the inclusion of...
Why not just use "... will include..."?

But I don't want that accessory, why is it included? Can I get a discount if it's not included? Can I buy it later if I think I need it? How will I know if I need it? It was already included and I didnt ask for it; can I take it off because it's ugly? I'm ordering replacement parts, I need X and Y critical components that were damaged, Z accessory was damaged too but I don't see any reason that it's essential so do I have to replace it? I do? I think you're BS'ing me just to make that sale.

Is all that really worth deleting 3-4 words?

RE: More complicated than necessary?

As for the first question, I always try to write as if the report is being read by a jury.  Frequently these reports are used in court cases, so they would have to be read and understood as well as could be explained by someone not in the engineering profession.  That takes extra wording.

As for the second, if you are going to use engineering terminology, you have to explain it to the loevel of anticipated audience that will read or hear it.  Otherwise it is useless.  I still keep the jury scenario in mind here too.

Mike McCann
MMC Engineering
http://mmcengineering.tripod.com
 

RE: More complicated than necessary?

(OP)
I definitely understand the need for clear and concise language, but I started this thread with the understanding that:

a) the target audience is intelligent enough to understand what I would describe as obvious (see example above)

b) the level of English in the target audience is not high

Regarding point b, I believe that if the target audience is fluent in English, then I wouldn't have a problem with the word choices. I am, however, more concerned with the potential difficulty in translation when we have to send the report to the clients. This is especially true when the people doing the translations are the engineers themselves rather than professionals who deal with these things.

RE: More complicated than necessary?

Often people add words trying to make things idiot-proof, but they forget that, no matter what, there is always a bigger idiot out there.

I say  Eschew Obfuscation.

RE: More complicated than necessary?

Yes, avoid obfuscation by all means, but also attempt ensure correct interpretation under any foreseeable circumstance.  Being diligent in clearly conveying intent is different that merely confusing the issue by being verbose.

"Good to know you got shoes to wear when you find the floor." - Robert Hunter
 

RE: More complicated than necessary?

If your writing allows interpretation, it will be interpreted incorrectly by someone....

As clear as our intent might be to us (as the author), it is not always so clear to others....and besides, idiots come in all forms, though many are concentrated in management.

RE: More complicated than necessary?

I have modified a couple of points from lecture notes I put together a few years back for visual presentation - this is easily adapted to technical writing:

Be clear in your own mind what you writing about

Be aware of why you are writing the report /technical paper

Who are you writing to

Use language the reader will understand

Keep it simple and specific (KISS)
  

It is a capital mistake to theorise before one has data. Insensibly one begins to twist facts to suit theories, instead of theories to suit facts. (Sherlock Holmes - A Scandal in Bohemia.)  

RE: More complicated than necessary?

Terseness!

- Steve
 

RE: More complicated than necessary?

Why state the obvious?
[1] The obvious won't be obvious to every reader, especially if there are people outside your target audience who will eventually read the report.
[2] Each report needs to stand on its own, and it requires a "foundation" to do that.

==========
"Is it the only lesson of history that mankind is unteachable?"
--Winston S. Churchill

RE: More complicated than necessary?

If a large number of your readers do not normally use English - or are iffy, they will put your words, phrases and even whole pages through Google Translate or other online translators.  Try a few of your sentences and paste back to see how they can be messed up.

I use formal English. [It also helps that I frequently speak with people in France and Mexico who keep me aware of jargon.

Another thing you can try is to use typical readers to give you feedback.  Ask one or two to read it and tell you what they are confused about - or ask them questions to see if they understood.

 

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! Already a Member? Login


Resources

Low-Volume Rapid Injection Molding With 3D Printed Molds
Learn methods and guidelines for using stereolithography (SLA) 3D printed molds in the injection molding process to lower costs and lead time. Discover how this hybrid manufacturing process enables on-demand mold fabrication to quickly produce small batches of thermoplastic parts. Download Now
Design for Additive Manufacturing (DfAM)
Examine how the principles of DfAM upend many of the long-standing rules around manufacturability - allowing engineers and designers to place a part’s function at the center of their design considerations. Download Now
Taking Control of Engineering Documents
This ebook covers tips for creating and managing workflows, security best practices and protection of intellectual property, Cloud vs. on-premise software solutions, CAD file management, compliance, and more. Download Now

Close Box

Join Eng-Tips® Today!

Join your peers on the Internet's largest technical engineering professional community.
It's easy to join and it's free.

Here's Why Members Love Eng-Tips Forums:

Register now while it's still free!

Already a member? Close this window and log in.

Join Us             Close