Best Writing Advice for Engineers I've Ever Seen. | Hacker News Reader

Best Writing Advice for Engineers I've Ever Seen.

engineerwriting.jottit.com

318 pointspetercooper73 comments

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/...). 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.

It's slightly amusing that the first sentence of the linked article is grammatically incorrect

I was actually tempted to drop the first paragraph of the quote, but thought against it considering the etiquette in these cases. The second paragraph is where the meat is :-)

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

Better still is Style: Lessons in Clarity and Grace. Writing with Power is also good, but a bit heavy on the wishful thinking in places.

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:-)

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.

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.

I try to fit my whole message in the subject line (ensuring readability, of course).

Literature == art

Journalism == engineering

(both of the written word).

Complaining that literature is a waste of time is like saying I can't paint my house with oil paints and a tiny brush. Technically true, but you're really missing the point.

Art is a fairly subjective thing, and I found literature as presented in high school to be a complete waste of time. And no, I'm not missing the point. Looking back, it really did not have any redeeming value for me. That's the way my brain is wired, and I won't be ashamed of it just because "society" thinks literature is great. I don't, and I'll say so if I please without 'missing the point'.

On the other hand, I loved the visual arts courses I took. Thanks in part to a good teacher, I found a lot to appreciate even in works I found "ugly" at first glance.

A large part of primary and secondary education is exposing you to different vocations, at least in part. Taking a course and recognizing that it's not for you is an invaluable experience, especially at such a young age. Think of it as the shotgun approach: Try a little of each to assess your desire and aptitude.

Yes, that's certainly fair and sensible. The problem is that lit is one of those things that you had to take every year where I went, so the only respite from it was a year of journalism.

I doubt he's saying the entirety of literature is a waste of time, just the way his literature class (and by extension most of them) was run.

Literature isn't about writing anymore than Computer Science is about programming. Part of your bad experience seems to stem from you not realizing this. The CS equivalent is assuming you're going to learn how to program in Theory of Computation.

The other part of your bad experience comes from the fact that your instructor was a poor educator. Grading solely based on the instructor's interpretation of the work is the canonical teaching mistake in English. Of course, having a bad instructor will make any course a bad experience, regardless of the discipline.

It's unfortunate your experience was so terrible because I find English to be very worthwhile. I've taken some of the most advanced undergraduate CS courses in the country and they were very worthwhile. Yet AP Engish senior year in high school and one English course in college match the CS courses in terms of being worthwhile.

I think it's best to clarify what I mean by worthwhile. One worthwhile moment in Computer Science was when I finally understood Lisp macros. Another one was when I understood Turing Machines. I'd say I've had about 5 or 6 of these moments over the past few years in CS. These are moments where you feel like you understand something in a fundamentally different and higher way. English produces similar moments, but they are about the world at large instead of just a technical field. Taking one English course per semester has netted me one or two worthwhile moments a month. It's really quite something.

If you're ever given the opportunity, I urge you to give literature another try. It's difficult to find a competent teacher, but it's worth the effort.

I got a lot more out of journalism because it was about how to effectively communicate something to other people, which is an extremely valuable skill. "Learning" to "analyze" (i.e. parrot something the teacher told us. And as far as I can tell he never consulted the author of the work to verify the correctness of his assertions) the symbolism in Ionesco's plays is to me, worthless.

> It's difficult to find a competent teacher

Great teachers in any field are rare, but I found the lit ones to be particularly mediocre. I think it's a field where you can do ok even if you talk out your ass and hand-wave, whereas, say, a physics teacher at least ought to know the material he's teaching, even if he's not the best at conveying it. Truth be told though, the physics teacher I had in HS was one of the really good ones. He was a smart guy, and while at first seemed quite 'harsh', in reality he was demanding and expected precision. I learned a lot from him.

"...but I found the lit ones to be particularly mediocre"

That's a gross generalization. You're basing that statement on your personal experience with many a handful of 'lit' teachers, out of the thousands of lit teachers, and trying to make a generalized statement about all of them? Please.

Maybe the ones you had were mediocre, but just leave it at that.

I wrote:

"I found" ... "I think". The first is certainly my personal experience, and the second is a theory that is clearly labeled as my opinion, which I am entitled to.

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.

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.

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 . . .

hm, wavelet analysis on (source) code... strange notion, and intriguing.

i've long thought that language is a fine tool to deliberately construct notions beyond our horizon.

composing such nonsense sentences feel like fuzzing the brain's pattern recognition.

You might enjoy the topic of the Professor's symposium in the "Futurological Congress", by Stanislaw Lem.

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."

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.

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.

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.

It's called the "Inverted Pyramid" and anyone who has taken a journalism class worth anything learned it.

It's there so that editors can cut down the story easily if it doesn't fit on the page. Page design is really hard if you can't change the size of some of the stories.

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.

http://www.amazon.com/Elements-Style-Fourth-William-Strunk/d...

Counterpoint: http://chronicle.com/article/50-Years-of-Stupid-Grammar/2549...

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.

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.

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.

This issue is deeply divisive, and I think the real problem often goes unstated. Here's my take on it.

Traditional grammar - the kind you learn in American grammar schools for example - is kind of a mess. It's jumble of very different things: (reasonable and unreasonable) tips about usage, spelling mnemonics, advice about grammar that has more to do with Latin than English, personal pet peeves and (no doubt) some very good grammatical rules.

This kind of grammar - traditional grammar - has nearly nothing to do with grammar as studied in linguistics departments at the university level. In fact, the scholars of linguistics are quite sure that much of traditional grammar is false, unhelpful and confused. (I'm on their side, but that's not really my point here. I'm just trying to sketch out why people keep fighting about 'grammar'.)

The two groups spend most arguments talking completely past each other and (unfortunately for the rest of us) very very loudly.

(A good test question, by the way, is the split infinitive in English. If you think it's a grammatical mistake, you're following traditional grammar. If you think it's entirely correct usage, you're probably someone with some linguistics training or background.)

Anyhow, the Strunk & White book and Lynne Truss's Eats, Shoots & Leaves are the kind of rulebook that makes linguists spitting angry. See Louis Menand's review of Truss, for another example of this: http://www.newyorker.com/archive/2004/06/28/040628crbo_books...

After reading that I am very glad that I never read that book. (Passive voice is a favorite of mine.)

The passive voice should be avoided.

If it were less deliberately controversial it would be more digestible. As is, some of his points seems inconsistent, but that may be due to presentation.

Pullum on Language Log today: http://languagelog.ldc.upenn.edu/nll/?p=2235

Maybe he's "right" in some sense, but I can't stand this guy. That level of anger and hate against Strunk and White seems strange and unwarranted. I think people shouldn't preach about style until they can write something that's not unpleasant to read.

Contrast this to White himself, who is quite enjoyable.

I think he's correctly assumed that this will get him more readers.

To me the important part of "Strunk and White" is the White part -- that is, the part that deals with style. Of course you should use good grammar or something close. The important thing isn't following grammar rules, but in expressing yourself well. There are a lot of bad grammatically correct sentences.

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.)

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.

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...

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

Engineers finally discover the inverted pyramid.

aka "How to write a high school essay."

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.

I think the basic advice offered in the article is solid. It's not in the most aesthetically pleasing style, but what are you gonna do. I guess I just don't hate minor sentences as much as you do.

Yes, it's solid advice, but it is basic. If we're talking about "engineers", that probably means they have completed a college degree at some point. If an engineer completed a degree and didn't take a technical writing course that drilled these concepts into their heads, then I question the quality of such an engineer's education.

I think you underestimate the ability of some people to pass classes without learning anything. I met an engineering student who had somehow passed a tough, high-quality technical writing class and yet could not write a coherent sentence, let alone a useful paragraph. I suspect that he cheated his ass off in most of his classes.

You know, I feel no sympathy for such people. If the reason they don't know how to write "well-enough" is because they cheated their way through college, then they deserve whatever lack of career opportunities they find themselves in.

It's worth noting that the advice is just a comment left on an Edward Tufte thread (which, as a whole, is a lot more interesting): http://www.edwardtufte.com/bboard/q-and-a-fetch-msg?msg_id=0...

this wasn't clear to me from the link provided.

edit: actually, this is an excellent demonstration of bad writing -- or rather 'blogging -- on behalf of whomever runs engineerwriting.jottit.com. The post is a straight copy out of another source, with a link to the source, with no explanation of what is going on, no discussion on the material, no value-add in general.

This is something that I struggle with in my link-sharing emails to my friends. After literally thousands of link-share emails, it starts to get hard to say something original beyond "I thought this was funny/interesting/etc", which eventually becomes practically worn into my keyboard. But then this is a good indicator to me that maybe the link isn't worth sharing. If I can't come up with something more interesting to say than "this is funny", then I don't need to be wasting my friends' time with it, because they have their own lists of pages that they peruse and they don't need me filling up their inbox with 25 new conversation threads in a single day.

I pasted it to Jottit because a) I don't have a blog that's relevant to the topic, b) the original comment is hard to link to accurately due to sloppy coding on ET, and c) I wanted to try Jottit after learning about it. I considered adding an explanatory paragraph, but I felt it could be crude and self-promotional (if someone says something, they should have their name against it) as the quote stands alone pretty well.

The issues you raise regarding link sharing are valid, and exist, but in this case it's really just a cut and paste job (and if it were not interesting, I doubt it'd get 100 upvotes here). I could have put it on Gist, Pastie, or 101 other sites. The quote is the whole bit. No analysis necessary.

Nonetheless, this would have worked better as a brief personal blog post. If I get back into personal blogging, I'd certainly tackle it that way instead.

How about:

Make engineers write concise sentences by combining journalism with the technical report format. Paragraphs in a newspaper article are ordered by importance, so that at whatever point readers stop reading they know that the part they have read was more important than the part left unread.

I think the second paragraph is pretty good, especially given the emphasis on concise sentences.

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.

Recently, Copyblogger had a good article elaborating on just what you said: http://www.copyblogger.com/tips-for-better-writing/

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.

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

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

Seems to be a technical version of "How To Write A Five-Paragraph Essay."

Thankfully, the ability to write well never loses favor.

If this is how you were taught to write high school essays, you were lucky.

   I. Introduction
  II. Body
      A. Point 1
      B. Point 2
      C. Point 3
 III. Conclusion

-5 points for each deviation.

Don't forget, if ranked by order of importants, the body should be:

    Point 2
    Point 3
    Point 1

I was also taught that the introduction must consist of a sentence that brings the reader to the topic, followed by the topic itself, and then a short description of points 1, 2 and 3. Again, any deviation will be penalized to the full extent of the law.

    A. Point 1
       1. Topic Sentence
       2. Concrete Detail
       3. Commentary
       4. Concrete Detail
       5. Commentary
       6. Commentary
       7. Transition Sentence

That format was driven into our heads in high school. When I was a freshman in College, I was amazed that very few of my peers could write an essay - a skill I had thought to be pretty basic.

At the time, I wondered, "if they didn't learn how to write an essay in high school, what did they learn?" I never really found out.

Actually I find it quite different from high-school essays.

In the "5 paragraph essay" you have 3 ideas, in the middle, and you summarize them in the intro and re-summarize in the conclusion. This advocates the journalism focus of getting your big idea out early, and expanding if needed. Most high school essays wouldn't teach you much reading just the title + abstract (first paragraph).

In real life you have a lot of information about your audience. You can guess whether jargon and equations will help or hinder communication. You are probably not reduced to guessing, you can go and ask your audience. They may come to you. This is probably not the first time you have written for them, you probably have valuable knowledge from last time.

Today's audience is not your only audience. Although you have valuable knowledge it may be in a bit of a jumble, with considerations that apply differently to different audiences clearly labelled as to whether they worked but not so clearly labelled as to the particular audience that delivered its verdict.

This deficiency is likely because high school essay writing has no audience, which trains you to ignore the most important question about writing: who is this for?

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.

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

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

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

Be clear, concise and to the point.

Entertain or inform. Do both for bonus points.

Be logical and honest.

Reply on news.ycombinator.com