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?
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?
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?
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?...
That statement suggests that an action is being made possible only because something is being included.
RE: More complicated than necessary?
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...
What is Engineering anyway: FAQ1088-1484: In layman terms, what is "engineering"?
RE: More complicated than necessary?
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?
RE: More complicated than necessary?
What is Engineering anyway: FAQ1088-1484: In layman terms, what is "engineering"?
RE: More complicated than necessary?
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?
RE: More complicated than necessary?
Excellent example!!!
RE: More complicated than necessary?
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 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?
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?
I say Eschew Obfuscation.
RE: More complicated than necessary?
"Good to know you got shoes to wear when you find the floor." - Robert Hunter
RE: More complicated than necessary?
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?
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?
http://en.wikipedia.org/wiki/Fog_Index
f-d
¡papá gordo ain't no madre flaca!
RE: More complicated than necessary?
What is Engineering anyway: FAQ1088-1484: In layman terms, what is "engineering"?
RE: More complicated than necessary?
- Steve
RE: More complicated than necessary?
Matt Lorono, CSWP
Product Definition Specialist, DS SolidWorks Corp
Personal sites:
Lorono's SolidWorks Resources & SolidWorks Legion
RE: More complicated than necessary?
[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?
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.