8 ms·
Best Writing Advice for Engineers I've Ever Seen.
- Mc_Big_G 17y agoaka "How to write a high school essay."
- moron4hire 17y agoAdditionally, 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.
- gamache 17y agoI 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.
- moron4hire 17y agoYes, 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.
- sketerpot 17y agoI 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.
- moron4hire 17y agoYou 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.
- petercooper 17y agoIt'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=0001yB http://www.edwardtufte.com/bboard/q-and-a-fetch-msg?msg_id=0...
- moron4hire 17y agothis 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.
- petercooper 17y agoI 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.
- jimbokun 17y agoHow 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.
- TheSOB88 17y agoSo 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.
- petercooper 17y agoRecently, Copyblogger had a good article elaborating on just what you said: http://www.copyblogger.com/tips-for-better-writing/ http://www.copyblogger.com/tips-for-better-writing/
- moron4hire 17y agoI 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 17y agoBut why does a blog post have to be formal in the first place?
- moron4hire 17y agoBecause you deign to waste our time with it. Putting effort into your writing shows that you have respect for your readers.
- johnohara 17y agoSeems to be a technical version of "How To Write A Five-Paragraph Essay." Thankfully, the ability to write well never loses favor.
- dkarl 17y agoIf 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.
- pavel_lishin 17y agoDon't forget, if ranked by order of importants, the body should be: Point 2 Point 3 Point 1
- ramchip 17y agoI 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.
- david 17y agoA. Point 1 1. Topic Sentence 2. Concrete Detail 3. Commentary 4. Concrete Detail 5. Commentary 6. Commentary 7. Transition Sentence
- biotech 17y agoThat 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.
- kalid 17y agoActually 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).
- alan-crowe 17y agoIn 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?
- chasingsparks 17y agohttp://www.amazon.com/Elements-Style-Fourth-William-Strunk/dp/020530902X http://www.amazon.com/Elements-Style-Fourth-William-Strunk/d...
- nollidge 17y agoCounterpoint: http://chronicle.com/article/50-Years-of-Stupid-Grammar/25497 http://chronicle.com/article/50-Years-of-Stupid-Grammar/2549...
- deleted 17y ago[deleted]
- Terretta 17y agoAs 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 17y agoYou'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 17y agoThe 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.
- alaithea 17y agoThis 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.
- Groxx 17y agoIn 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 17y agoActually, 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 17y agoI 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.
- assemble 17y agoIt'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.
- jgrahamc 17y agoWhen 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/dp/0062735233 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.
- petercooper 17y agoIt'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 :-)
- mcburton 17y ago"On Writing Well" is one of my favorite books! I try to read it at least once a year.
- Estragon 17y agoBetter still is Style: Lessons in Clarity and Grace. Writing with Power is also good, but a bit heavy on the wishful thinking in places.
- swombat 17y agoOn a slightly more elaborate and potent level, try "The Pyramid Princple" by Barbara Minto: 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 http://www.amazon.co.uk/Pyramid-Principle-Logic-Writing-Thin...
- DanielStraight 17y agoI'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.
- davidw 17y agoJournalism 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 17y agoAgreed. 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 17y agoActually, 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.
- kbob 17y agoThis 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.
- dmlorenzetti 17y agoThe 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."
- hxa7241 17y agoThe 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 17y agoI 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 17y agoIt 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 . . .
- cracki 17y agohm, 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.
- oofoe 17y agoYou might enjoy the topic of the Professor's symposium in the "Futurological Congress", by Stanislaw Lem.
- RyanMcGreal 17y agoEngineers finally discover the inverted pyramid.
- mkramlich 17y agoBe clear, concise and to the point. Entertain or inform. Do both for bonus points. Be logical and honest.
- pchristensen 17y agoThis also applies to writing email. You should be able to get your point across in your subject.
- chasingsparks 17y agoGood 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.)
- angelhaze218 17y agoam really not understanding why this is so popular, period. I thought those were general rules for good writing, period.
- angelhaze218 17y agoam I missing something here, not period, question mark?