Number 34
I'm editing something that was written by an intelligent person, quite perceptive and sharp-thinking, technically, who seems to fumble hopelessly with some sentences. Example (NOT for publication as is):
. . . logic can be built within a web application, but the details of executing complex logic for this client’s project actually take place in an IDE (Integrated Development Environment) which ~ while open-ended ~ could have an extremely convoluted development process for the client’s needs.
My challenge, in coaching this relative youngster, is to figure out what she's doing wrong ~ explain to her what she's not making clear.
Do you know of any corrective courses (or textbooks) for people whose grammar is okay but whose meaning is obscure? I think that's the case with this writer; her grammatical errors are at the relatively minor (these days) level of not knowing that "criteria" is plural. It's not unusual to find a paragraph where it's hard to detect what the heck she's even talking about. Yet, when I talk it out with her, I find she has a perfectly good point. And in other passages the writing is fine. That's what leads me to suspect that in some situations she just can't straighten out what she's trying to say.
In the above example, I suspect "executing" is the wrong word ~ I suspect she meant "defining." And I suspect she meant "could be an extremely convoluted . . .", not ". . . could have." And I suspect "open-ended" refers to a supposed advantage. So the whole thing might come out:
. . . logic can be built within a web application, but the details of defining complex logic for this client’s project actually take place in an IDE (Integrated Development Environment) which ~ while it has the advantage of limitless flexibility, since it's open-ended ~ could be an extremely convoluted way to fulfill the client’s needs.
(I'd break it into smaller sentences, but that's a separate subject.)
If my guesses are correct, then her errors include:
The bottom-line impact of these errors is that the knowledge in her head wasn't communicated to the client ~ and in that respect, the report simply failed, like a truck that went to the right house and tried to drop off the package but got it wrong.
Maybe we can clean this up somehow ("anonymize" it) and post it for your lovely readers, in case someone knows of a good book of practical writing for intelligent adults who didn't get as much in school as they now wish they had.
This is one of those common cases where it's hard to know where to start. I found different flaws in the sample of writing than those above, which further shows the weaknesses of the writing.
First, off hand I can't think of a one-stop, all-purpose manual to correct this kind of writing, or thinking, although there are many good stylebooks. As you know, refining one's thought processes, and thus language, is a lifetime job. For starters, I could suggest Fowler's Modern English Usage (not the revised version). Interesting reading that requires careful attention and thought. If your client is interested, she may move on to other material; or she may decide Fowler is too old-fashioned and not "relevant" to modern tech writing. Any suggestions, Readers, gentle and otherwise?
But I do have two general principles for her:
ONE: Consider the reader. Is she writing for a general audience or a technical audience? Tell her to imagine she's trying to explain something to an intelligent person who doesn't know the technological jargon. Her mother, maybe, or an intelligent 12-year-old. She could think of herself as a teacher ~ always keeping the phrase "in other words" in mind. Never assume.
I remember when I was first using computers, it was very difficult for me to learn from manuals because the writers then were specialized computer geeks who really only wanted to talk to each other, and would have preferred to keep it a closed club (a la the evil literature professor ~ "You'd like me to tell you, wouldn't you?" [Maniacal laughter]). At least that's how it seemed. The instructions might leave out one keystroke because the writers did whatever it was automatically and could not put themselves in the heads of rank beginners. Or they'd use technical terms with no glossary.
A glossary might be needed for the term "open-ended", though maybe not. I've done a lot of technical editing, and I think here it means adaptable in some way, easy to modify or upgrade, or to connect with other systems ~ which is advantageous but does not mean "advantageous". I've read "open architecture" many times, and presume it has a specific, non-replaceable meaning for computer geeks (and as a writing geek, I say "geek" with all due respect).
Likewise, I'm not sure if "executing" should be "defining" since she seems to be describing the construction of some kind of computer system or web application. I'd have to know more. I'm not a programmer or systems analyst or application designer.
I once made the mistake of "correcting" an engineering report because I thought "actuate" was an unnecessary variation on "activate", not knowing that it's a commonly used term in engineering. It's always a good idea to ask the writer, if there is the slightest possibility of confusion. On the other hand, tech writers need to be educated in writing clearly, even when they're using specialized jargon and even when they're writing for a tech readership.
TWO: Tell her to try to cut out half the words while still making sense. This will sharpen her language terrifically, it's a great discipline. That phrase ~ "could have an extremely convoluted development process for the client’s needs" ~ is way too wordy for the amount of meaning conveyed. I can reduce it from 11 to 3 words with:
... is too convoluted.
As is her writing. Go over it word by word and phrase by phrase with her ~ think about every word:
In the beginning of the selection, "into" might be better than "within" and "the details of" can probably be eliminated entirely without changing the meaning. So another possible rewrite ~ not necessarily the best possible ~ could be:
. . . logic can be built into a web application, but executing complex logic for this client’s project actually takes place in an IDE (integrated development environment) which ~ while open-ended ~ is too convoluted.
And by the way, just because an acronym is all caps (IDE), that doesn't mean what it stands for needs to be capitalized. An acronym does not turn a commonly used phrase, even in a specialized field, into a proper noun or phrase (think of RPM or MPH or QED).
There's no reason to pad technical writing ~ clarity and simplicity are the first and only goals. You want to usher the overtaxed reader in and out of your material ~ to be read out of necessity, not for pleasure ~ as quickly and efficiently as possible. So, a good general rule to follow is, what words and phrases can you eliminate without changing or losing meaning? The only reason to write something longer instead of shorter is to achieve fine nuances, which is not quite the same as fine logic; or for euphony, which is beyond her ability and needs at this point.
But every writer can aim for elegance, in the sense of
"an elegant mathematical solution ~ simple and precise and lucid . . . combining simplicity, power, and a certain ineffable grace of design. . . . The French aviator, adventurer, and author Antoine de Saint-Exupe'ry, probably best known for his classic children's book The Little Prince, was also an aircraft designer. He gave us perhaps the best definition of engineering elegance when he said 'A designer knows he has achieved perfection not when there is nothing left to add, but when there is nothing left to take away'."
www.yourdictionary.com
You can go over her own specific examples with her and hope that the general principles sink in. Parvum Opus 6, "Deadheading", addresses cutting, with a few examples of useless filler words. I think it's harder for weak writers to start with general principles of writing (e.g. conciseness, clarity, etc.) and then try to apply them. It's one thing to say "Think and speak clearly!" and quite another for the person to understand how. Better to work with the specifics.
But this is why the world needs editors.
Copyright Rhonda Keith 2003. Parvum Opus or part of it may be reproduced only with permission, but it is permissible to forward the entire newsletter as long as the copyright remains.
Parvum Opus is a publication of KeithOps / Opus Publishing Services. Feel free to comment in the Guestbook, linked below the back issue links.
Feel free to e-mail me with comments or queries. If you don’t want to receive Parvum Opus, please reply with “unsubscribe,” “quit,” “enough,” or something like that in the subject line, and I’ll take you off the mailing list.
Return to KeithOps.