4 ms·

i agree that this is important but the article is light on recommendations for improving written comms. anyone have experience?

jugjug 6y ago
I've found Steven Pinker's book on writing useful & spot-on [1] [1] https://www.goodreads.com/book/show/20821371-the-sense-of-style https://www.goodreads.com/book/show/20821371-the-sense-of-st...
jkingsbery 6y ago
The large tech company I work for puts a lot of emphasis on writing. Here are a few suggestions: 1. If you want people to read what you wrote and give you feedback, conciseness is important. We have a general rule of thumb that it takes people 30 minutes to read 4-6 pages of terse material, and it takes roughly an hour to then discuss it. As a result, pretty much all our docs are 6 pages (in the main body; appendixes might be added but are written in a way so that the doc stands on its own without them). 2. For many forms of (non-fiction) communication, the inverted pyramid is a helpful way to structure your thoughts. People are most likely to read the beginning of something, When we read the whole thing, we're more likely to pay more attention to the beginning. It's important then to get the most important information in the beginning, with supporting details as you go. 3. Know the audience, and focus on why the audience should care. If it's not clear why the audience would care, try rephrasing or restructuring to focus on the part they actually would care about. 4. Do lots of iterations. Get feedback from others. You can also iterate on your writing yourself: I find that when I write something and come back to it later, I'm better at finding issues. In order to do a lot of iterations, that means you need to plan out your time. In my company, we often kick-off the doc writing process with a "working backwards" schedule: we're presenting to such-and-such VP on Day X, so we have to have a rough draft of the whole doc on Day Y, so we have to have drafts of individual pieces by Day Z. 5. Be aware of what kind of thing your writing. I'd say 75% of my writing, my audience is myself: I'm writing in order to work through thoughts. I approach that differently when I'm writing something for review by teammates, which I again approach differently from a doc written for other groups. 6. Maybe a bit controversial in some circles, but: Strunk and White (https://www.amazon.com/Elements-Style-Fourth-William-Strunk/dp/020530902X https://www.amazon.com/Elements-Style-Fourth-William-Strunk/...). It's a short book, and even if you don't do everything in it, the focus on clarity and succinctness is still useful.
- hef19898 6y ago
  It still puzzles me how much being forced to stick to 6 pages, ideally completely data based, helps to form concise thoughts and concepts.
  - jkingsbery 6y ago
    It doesn't make forming them any easier, it's just a forcing function to spend longer on the task. While it certainly is possible to have a topic that just cannot be handled in 6 pages, my experience is that after removing weasel words, filler, non-essential details, adverbs and the like, 6 pages is enough to base a conversation on most topics when the group has basic familiarity with the subject matter.
- ghaff 6y ago
  >As a result, pretty much all our docs are 6 pages (in the main body; appendixes might be added but are written in a way so that the doc stands on its own without them). It's good to use appendices when there's a lot of background (whether technical/history/etc.) that really isn't important to the central thrust of the document. Also, even at 6 pages, I'd probably recommend some sort of executive summary.
- djohnston 6y ago
  this is excellent feedback, thanks!
wenc 6y ago
In business writing, the Pyramid principle (a method formalized at McKinsey) is often used. It's the exact inverse of academic writing where you start with foundations and build up arguments. https://medium.com/lessons-from-mckinsey/the-pyramid-principle-f0885dd3c5c7 https://medium.com/lessons-from-mckinsey/the-pyramid-princip... Quote: 1. Start with the answer first. 2. Group and summarize your supporting arguments. 3. Logically order your supporting ideas. The author also proposes combining this with the Rule of 3 -- not more than 3 items (arguments, ideas, bullets) in a group. I've used these techniques in real life and can vouch for their effectiveness.
- hansvm 6y ago
  Is that really the case with academic writing? Viewing a paper as a whole I tend to think that the abstract and intro more or less map to (1) and (2) from your quotation. Abstract: Briefly describe why the audience cares, what you did, and what the results were so that they know whether they should read more or move on to something else. Intro: Same as abstract but in more depth and with an emphasis on helping the reader decide if the meat of the paper is worthwhile for them. Nearly every other section: Specifics vary by field, but there will generally be an argument from foundations as you describe, and elements which don't fit naturally in the flow of that argument are given their own headers (certain experimental details, foundational algorithmic appendices, ...)
  - Jtsummers 6y ago
    I almost wrote a similar comment, but academic paper abstracts can be highly variable. They don't always include the conclusion, or without sufficient detail to act on it without reading the actual conclusion section. This contrasts with the style GP talks about (also used in the US military, referred to as "Bottom Line Up Front" or "BLUF"). The first thing is the conclusion/actionable part with enough detail to start acting without needing to read the rest, and often zero justification (more a statement of fact or a directive: we will do X starting on Monday). Most of the rest contains things like analysis of alternatives or rationales, useful for some of the people to use but not essential for most to read. Some academic papers (taken as a whole) are similar to this, but it's not universal.
mooreds 6y ago
I had a guest poster write an article for a blog I run called "Always be journalling": https://letterstoanewdeveloper.com/2018/12/14/always-be-journaling/ https://letterstoanewdeveloper.com/2018/12/14/always-be-jour... where he talks about tips and tricks for journalling and how it makes you a better writer.
syndacks 6y ago
Read more books. Seriously, it's the best way to improve your writing.

jugjug 6y ago

I've found Steven Pinker's book on writing useful & spot-on [1] [1] https://www.goodreads.com/book/show/20821371-the-sense-of-style https://www.goodreads.com/book/show/20821371-the-sense-of-st...

jkingsbery 6y ago

The large tech company I work for puts a lot of emphasis on writing. Here are a few suggestions: 1. If you want people to read what you wrote and give you feedback, conciseness is important. We have a general rule of thumb that it takes people 30 minutes to read 4-6 pages of terse material, and it takes roughly an hour to then discuss it. As a result, pretty much all our docs are 6 pages (in the main body; appendixes might be added but are written in a way so that the doc stands on its own without them). 2. For many forms of (non-fiction) communication, the inverted pyramid is a helpful way to structure your thoughts. People are most likely to read the beginning of something, When we read the whole thing, we're more likely to pay more attention to the beginning. It's important then to get the most important information in the beginning, with supporting details as you go. 3. Know the audience, and focus on why the audience should care. If it's not clear why the audience would care, try rephrasing or restructuring to focus on the part they actually would care about. 4. Do lots of iterations. Get feedback from others. You can also iterate on your writing yourself: I find that when I write something and come back to it later, I'm better at finding issues. In order to do a lot of iterations, that means you need to plan out your time. In my company, we often kick-off the doc writing process with a "working backwards" schedule: we're presenting to such-and-such VP on Day X, so we have to have a rough draft of the whole doc on Day Y, so we have to have drafts of individual pieces by Day Z. 5. Be aware of what kind of thing your writing. I'd say 75% of my writing, my audience is myself: I'm writing in order to work through thoughts. I approach that differently when I'm writing something for review by teammates, which I again approach differently from a doc written for other groups. 6. Maybe a bit controversial in some circles, but: Strunk and White (https://www.amazon.com/Elements-Style-Fourth-William-Strunk/dp/020530902X https://www.amazon.com/Elements-Style-Fourth-William-Strunk/...). It's a short book, and even if you don't do everything in it, the focus on clarity and succinctness is still useful.

hef19898 6y ago
It still puzzles me how much being forced to stick to 6 pages, ideally completely data based, helps to form concise thoughts and concepts.
- jkingsbery 6y ago
  It doesn't make forming them any easier, it's just a forcing function to spend longer on the task. While it certainly is possible to have a topic that just cannot be handled in 6 pages, my experience is that after removing weasel words, filler, non-essential details, adverbs and the like, 6 pages is enough to base a conversation on most topics when the group has basic familiarity with the subject matter.
ghaff 6y ago
>As a result, pretty much all our docs are 6 pages (in the main body; appendixes might be added but are written in a way so that the doc stands on its own without them). It's good to use appendices when there's a lot of background (whether technical/history/etc.) that really isn't important to the central thrust of the document. Also, even at 6 pages, I'd probably recommend some sort of executive summary.
djohnston 6y ago
this is excellent feedback, thanks!

wenc 6y ago

In business writing, the Pyramid principle (a method formalized at McKinsey) is often used. It's the exact inverse of academic writing where you start with foundations and build up arguments. https://medium.com/lessons-from-mckinsey/the-pyramid-principle-f0885dd3c5c7 https://medium.com/lessons-from-mckinsey/the-pyramid-princip... Quote: 1. Start with the answer first. 2. Group and summarize your supporting arguments. 3. Logically order your supporting ideas. The author also proposes combining this with the Rule of 3 -- not more than 3 items (arguments, ideas, bullets) in a group. I've used these techniques in real life and can vouch for their effectiveness.

hansvm 6y ago
Is that really the case with academic writing? Viewing a paper as a whole I tend to think that the abstract and intro more or less map to (1) and (2) from your quotation. Abstract: Briefly describe why the audience cares, what you did, and what the results were so that they know whether they should read more or move on to something else. Intro: Same as abstract but in more depth and with an emphasis on helping the reader decide if the meat of the paper is worthwhile for them. Nearly every other section: Specifics vary by field, but there will generally be an argument from foundations as you describe, and elements which don't fit naturally in the flow of that argument are given their own headers (certain experimental details, foundational algorithmic appendices, ...)
- Jtsummers 6y ago
  I almost wrote a similar comment, but academic paper abstracts can be highly variable. They don't always include the conclusion, or without sufficient detail to act on it without reading the actual conclusion section. This contrasts with the style GP talks about (also used in the US military, referred to as "Bottom Line Up Front" or "BLUF"). The first thing is the conclusion/actionable part with enough detail to start acting without needing to read the rest, and often zero justification (more a statement of fact or a directive: we will do X starting on Monday). Most of the rest contains things like analysis of alternatives or rationales, useful for some of the people to use but not essential for most to read. Some academic papers (taken as a whole) are similar to this, but it's not universal.

mooreds 6y ago

I had a guest poster write an article for a blog I run called "Always be journalling": https://letterstoanewdeveloper.com/2018/12/14/always-be-journaling/ https://letterstoanewdeveloper.com/2018/12/14/always-be-jour... where he talks about tips and tricks for journalling and how it makes you a better writer.

syndacks 6y ago

Read more books. Seriously, it's the best way to improve your writing.