
Best Writing Advice for Engineers I've Ever Seen. - petercooper
http://engineerwriting.jottit.com/
======
jgrahamc
When I was working on my book O'Reilly sent me a copy of "On Writing Well" by
William Zinsser ([http://www.amazon.com/Writing-Well-Classic-Guide-
Nonfiction/...](http://www.amazon.com/Writing-Well-Classic-Guide-
Nonfiction/dp/0062735233)). I read the entire book and I thought it was well
worth it. One of his best pieces of advice is to end each paragraph leading
the reader to the next one; the reader should want to know more.

It's slightly amusing that the first sentence of the linked article is
grammatically incorrect: "How to make engineers write concisely with
sentences?" is not a question despite the question mark. The second sentence
is overly long and uses three commas to give the reader breathing space.

~~~
mcburton
"On Writing Well" is one of my favorite books! I try to read it at least once
a year.

------
davidw
Journalism class was the only worthwhile "language arts" class I took in high
school. The "literature" ones were, IMO, mostly a bunch of horse shit and a
waste of time, to put it very bluntly. There are classes and teachers that I
looked back on more fondly when I was done with them because I realized they'd
been good for me even if they were difficult, but none of the literature ones
were in that category, only the journalism class stuck with me as something
useful.

Why? Because the lit ones were about writing bullshit about some teacher's
bullshit interpretation of what was more often than not some sort of bullshit
book/essay/play/whatever, whereas the journalism class was about how to convey
facts to a hurried reader quickly and efficiently.

Ok... rant over:-)

~~~
billybob
Agreed. I've got a journalism background (though I'm now a web developer) and
it has helped me tremendously.

The main thing is this: think and write carefully. I get emails from business
people that are long, rambling, and at the end, I can't even tell what they
mean or want. And the subject line isn't helpful if I need to find it later.

I write emails with the assumption that you've got 5 seconds to read it.
Subjects like "Are we still meeting at 2PM today?" so you might not even need
the body, which is short and to the point.

Also, if I have three unrelated questions for someone, I write three short
emails. I want them to be able to answer two and flag one for later if
necessary, without drudging up the other issues that were already solved.

The other great lesson from journalism is "people have short attention spans."
The inverted pyramid is for hard news stories, but even fluff pieces try to
start with really catchy first sentences and be clear throughout. If you lose
people's attention too often, you lose your customers.

Many academics and businesspeople should learn from this - they often seem
more concerned with sounding smart than really conveying information. Great
ideas are no good if nobody hears about them. And in my experience, great
minds are generally good at explaining their ideas clearly.

~~~
billybob
Actually, let me backpedal a bit. I don't think literature is crap. SOME
literature is crap. But if all of it was, we wouldn't have a standard of
quality to judge by, would we?

Literature can be wonderful, and reading good stuff can help you write better,
too. But different styles of writing serve different purposes. I love Billy
Collins' poetry, but it doesn't help me write good business-related emails.
Neither does journalism help much when writing a love song.

------
hxa7241
The other important thing needed is:

 _Make your message concrete and specific._

It is no use reading a first sentence that says something like: "We created a
novel abstraction to improve software development.". Yes, it is concise, but
it says nothing. "We used wavelet analysis to find and factor-out the most
modified aspects of our code." -- _that_ I can see I want to know more about.

~~~
_delirium
I actually kind of find myself often wanting the opposite, especially in the
first sentence or two of a paper's abstract. If the first sentence has details
about their method, I'm often still trying to figure out of it's even on the
broad subject I'm looking for. Your first example would let me say, "oh ok,
their goal here was improving software development, not what I was looking
for", without being distracted by details about wavelets.

~~~
hxa7241
It is true that some useful information is missing from a specific statement,
but I would probably expect much of it would be supplied by the context of
where or how you found the document . . .

------
dmlorenzetti
The best writing advice I ever had as an engineer was, "Sure it can be nine
pages, but the journal charges $300 for every page over six."

------
Groxx
_In a newspaper article, the paragraphs are ordered by importance, so that the
reader can stop reading the article at whatever point they lose interest,
knowing that the part they have read was more important than the part left
unread._

I never knew that, though now that I've seen it said, it does seem accurate.
Articles do lose importance as the article goes on. But I'd argue that it's a
much older method, known as a "hook". Relying on a reader's knowledge of an
unstated rule / guideline is effectively suicide when dealing with large
quantities.

It does make good advice for engineers, though, especially as it's procedural.
Follow the steps for win. If couched in these terms, you'd probably get more /
better technical writing from most people.

~~~
JeremyStein
Actually, the main reason for putting the important parts first is to give the
newspaper editor flexibility for fitting stories onto the page. The end of a
story can be left off if there's not enough room.

~~~
antauth
I actually just read that the telegraph has something to do with it. Because
messages would often get cut off, the important content had to come first.

------
alaithea
This is similar to how one of my English TA's in college taught me to write
essays. Perhaps this is standard advice, but to hear it so plainly put was new
to me.

Paragraph 1: First sentence: Your thesis statement. Follow it with several
sentences that back up different aspects of your thesis. Write a paragraph for
each of those supporting sentences. The first and last sentence of each of
those paragraphs should be the original sentence stated a bit differently.
Last paragraph is a restatement of your first paragraph.

It sounds like a lot of repetition, but once I started following his advice,
my writing quality improved vastly. It tends to impart a razor-like focus to
the writing. Not to mention that the systematic quality of it almost makes it
feel like the paper is writing itself.

------
chasingsparks
[http://www.amazon.com/Elements-Style-Fourth-William-
Strunk/d...](http://www.amazon.com/Elements-Style-Fourth-William-
Strunk/dp/020530902X)

~~~
nollidge
Counterpoint: [http://chronicle.com/article/50-Years-of-Stupid-
Grammar/2549...](http://chronicle.com/article/50-Years-of-Stupid-
Grammar/25497)

~~~
Terretta
As on Fox News, for every opinion one can find a counterpoint.

This particular counterpoint does more damage than good in the age of TL;DR.

I'd rather read the writings of 'an educated person who knows they feel
vaguely anxious and insecure whenever they write "however" or "than me" or
"was" or "which,"' than the incoherence of someone who thinks grammar is
pointless.

I often see this counterpoint cited, but never its conclusion about "the
overopinionated and underinformed little book that put so many people in this
unhappy state of grammatical angst. I've spent too much of my scholarly life
studying English grammar in a serious way. English syntax is a deep and
interesting subject. It is much too important to be reduced to a bunch of
trivial don't-do-this prescriptions."

There's Drivers' Ed, and then there's Skip Barber Racing School. That experts
learn more doesn't mean novices should learn less.

~~~
nollidge
You've completely avoided reading Pullum's article, it seems. No one said
grammar is pointless. No one said novices shouldn't learn grammar basics. Only
that they shouldn't be taught falsehoods.

~~~
hugh3
The problem to me is the mismatch between Pullum's actual criticisms (which
are mostly entirely fair nitpicks about passive voice etc) and his "burn
Strunk & White" rhetoric.

But if he's got a better recommendation, or wants to write his own book, then
I'm all for it.

------
chasingsparks
Good writing comes from practice. You can learn guidelines, but they are just
that -- guidelines. (I posted Skunk and White below as something I used for
training wheels a long time ago.) I think programmers typically start out
writing stylistically worse than non-programmers because they are used to both
tools that supervise syntax and semantics that are easily testable (i.e. does
this work.)

Expressing ideas in written word is far less rigid. Happily, readers are
capable of parsing near non-sense. The can lex smyobls form gibebrsih and
construct meaning from ambiguity. Unfortunately, readers are under no
obligation to read what you have written. Whether you are trying to inform,
influence, or entertain, you first have to engage. Programmers -- and
engineers -- forget this lesson easily (if they ever knew it to begin with.)

------
DanielStraight
I've always written similar to this. In college, I always spent most of my
writing time on the opening paragraph. Then I just turned each sentence into a
paragraph (if it isn't important enough to warrant a paragraph, why is it in
the opening paragraph?) and added a conclusion. Admittedly, this doesn't work
for large papers (I think 5 pages is probably a reasonable limit), but I try
to avoid writing large papers whenever possible.

------
swombat
On a slightly more elaborate and potent level, try "The Pyramid Princple" by
Barbara Minto:

[http://www.amazon.co.uk/Pyramid-Principle-Logic-Writing-
Thin...](http://www.amazon.co.uk/Pyramid-Principle-Logic-Writing-
Thinking/dp/0273710516/ref=sr_1_1?ie=UTF8&s=books&qid=1270561639&sr=1-1)

------
pchristensen
This also applies to writing email. You should be able to get your point
across in your subject.

------
RyanMcGreal
Engineers finally discover the inverted pyramid.

------
Mc_Big_G
aka "How to write a high school essay."

~~~
moron4hire
Additionally, I tend to ignore writing advice from people who use incomplete
sentences. That page was a travesty.

edit: I didn't know this was a comment before I posted this, but it does bring
up issues with 'blogging in general.

~~~
TheSOB88
So do you never use such structures in speech? They're a way of getting the
point across clearly and succinctly. Just because they taught you it's "wrong"
in school doesn't mean that it doesn't have value.

~~~
moron4hire
I wasn't aware that this was a comment on another piece. Yes, I use less
formal grammar in less formal situations. I even experiment in the minimalist
form with haiku and other writing. Knowing now that it was a comment makes a
little more sense. Without knowing that, it just seemed like lazy writing.

~~~
TheSOB88
But why does a blog post have to be formal in the first place?

~~~
moron4hire
Because you deign to waste our time with it. Putting effort into your writing
shows that you have respect for your readers.

------
kbob
This came at the perfect time. I'm just starting to outline a series of
technical articles for my 'blog, and I was having trouble getting them
organized.

Thanks.

------
angelhaze218
am really not understanding why this is so popular, period.

I thought those were general rules for good writing, period.

~~~
angelhaze218
am I missing something here, not period, question mark?

------
mkramlich
Be clear, concise and to the point.

Entertain or inform. Do both for bonus points.

Be logical and honest.

