It's a strange realization but most of what we do as engineers is writing: writing docs, writing specs, writing project proposals, writing reports, even writing comments in our code. This writing should be precise, efficient and effective.
With all this writing, Writing (with a capital "W") should be considered a crucial engineering skills. Still, I don't know of any engineer who went through a technical writing class in college. It's not even something that's routinely proposed in corporate training for programmers, at least, I've never seen it listed anywhere.
At best, technical writing is considered a specialized writing style. It's a shame really since the fundamental and difficult part of technical writing is to extract and present relevant information in a concise and precise way.
I've been lucky enough in college to have an outstanding mentor: Georges Bronner. After the (disastrous) first draft of my short thesis, Georges gave me a 15 minutes course on technical writing. This is by far the most useful piece of teaching I ever received and one that I tried to communicate back to every intern or first time hire I had to mentor.
So, for the benefit of all and not just interns, and just so we get to the point, here's Georges' advices boiled down to a simple sieve:
- One idea per sentence.
- Separate assumptions from facts: don't put assumptions and facts in the same paragraph.
- Separate facts from interpretations: don't mix in the same paragraph data and interpretation of the data.
- Don't give opinions: no one cares... (Georges' own words here).
The shorthand on how to apply this set of advices could be know what you're saying.
This should not translate into writer's impotence though. Since the best writing is rewriting (E.B. White), put a paragraph down quickly then analyze it and separate hypothesis, facts, interpretations and opinions down to the level of words. Hunt down adjectives and adverbs: they are your enemies, they taint facts with opinions and interpretations.
Then, for each segment identified, ask honestly:
- What is the information in that segment?
- Is it a fact? A hypothesis? An interpretation?
- If it is a fact, do I have the original data?
- Do I have the source of this data?
- Do I have facts to back up that segment as a consequence of this one?
- Is it an opinion?
- Is it relevant?
If you find a fact not well corroborated:
- Consider suppressing it: will your point still stand?
- If not: get more data...
I call that Tufte applied to writing.
This little exercise will keep you honest and concise. It will also help your writing style, weeding out most cliches and unecessary words.
As far as style is concerned, there's no shortage of advice available through writing classes, books, news groups and web sites. Those style guides are useful of course: good technical writing is also good writing, clarity is important, using proper vocabulary, avoiding jargon also, etc... You can find all of this in Strunk and White's classic Elements of Style.
Style guides however are never about substance and content but about presentation. The content is your problem: it's assumed and supposed to be good.
So just don't limit your editing to style. The fundamental lessons given in Georges' sieve is never mentioned because it's not about style: it's about a deep understanding of what you say, identifying the information you transmit and, above all, being fanatically honest.