>Communication is like selling - it's all about return on investment. And ROI is all based on understanding abstractions (and how they leak). You need to give the reader/listener enough of a promise they're going to get value at least proportional to the time spent consuming what you're trying to convey that they want to stick around.
Ask HN: How to level up your technical writing?
141–150 of 162 posts
Re: Ask HN: How to level up your technical writing?
#142Earlier quoted context omitted.
> Oh, and use an editor (the human kind, not the digital kind.) This is so important (IMNSHO). It's fairly obvious, that editors are becoming a "lost art." My mother was a scientific editor, and she was brutal (she edited some of my work). It's really hard to find fiction books, that are less than 500 pages. I read a story about Stephen King. Apparently, he hates being edited (most writers don't like it). When he was…
Eh, depends...as you point out it is becoming a "lost art". The average quality of editors is utterly abysmal, so if you're pretty handy with style, or have lived under the cosh of an academic style guide for long enough you can probably get by without an editor.
I'd say the opposite
As someone who's recently been put back under the "cosh of an academic style guide", I can definitely say the "academic style guide" does NOTHING to help with editing ... it's all about FORMAT
Format is nice, and all ... but almost 100% irrelevant to the content
Re: Ask HN: How to level up your technical writing?
#143Earlier quoted context omitted.
> Oh, and use an editor (the human kind, not the digital kind.) This is so important (IMNSHO). It's fairly obvious, that editors are becoming a "lost art." My mother was a scientific editor, and she was brutal (she edited some of my work). It's really hard to find fiction books, that are less than 500 pages. I read a story about Stephen King. Apparently, he hates being edited (most writers don't like it). When he was…
> Apparently, he hates being edited (most writers don't like it). I've grown to love it. It was a long road. Once you start disciplined writing an editor becomes like a personal trainer who helps you be your best. Until I learned to write with more steel and less fire, ego ruled my writing. The familiar sins are; - loving the sound of your own (inner) voice - showing off what you know rather than considering what the…
Or maybe not-so-"gently" .. I'll take useful constructive criticism (regardless of harshness) over unactionable "reword" every dang day of the week (and 3 times on Sunday)
Re: Ask HN: How to level up your technical writing?
#144Earlier quoted context omitted.
https://www.btb.termiumplus.gc.ca/tpv2guides/guides/pep/inde... The suggestion is to never separate a subject from a verb or a verb from its object
Hey, thanks for that! Proper comma (and semicolon) usage is always a challenge for me. I decided to develop the habit of the "Oxford Comma," but I don't think I have it down, yet. It also seems to be "un-American." American English does not like commas.
But be consistent!
If you always use the Oxford comma, you never have any confusion.
When you sometimes use it and sometimes don't, confusion proliferates
Re: Ask HN: How to level up your technical writing?
#145Earlier quoted context omitted.
> Oh, and use an editor (the human kind, not the digital kind.) This is so important (IMNSHO). It's fairly obvious, that editors are becoming a "lost art." My mother was a scientific editor, and she was brutal (she edited some of my work). It's really hard to find fiction books, that are less than 500 pages. I read a story about Stephen King. Apparently, he hates being edited (most writers don't like it). When he was…
You can see exactly the same with other authors. Asimov and J. K. Rowling, to pick two obvious candidates. Compare "Foundation" with "Foundation and Earth" or "Foundation's Edge". Or "The Philosopher's Stone" with "The Order of the Phoenix". The former were well-edited and succinct. The latter were overly long, in some cases sorely repetitive with large amounts of padding, and a good editor could have cut them down b…
I've worked as a reviewer/editor (with "compensation" in the form of the acknowledgment page) on a handful of technical books
Overall, of the ~7 authors I've reviewed/edited, I can confidently assert only one was wrong, but ALL wrote in nearly-unfollowable ways
Re: Ask HN: How to level up your technical writing?
#146Earlier quoted context omitted.
I always like to point at Victor Hugo. In Les Misérables, apparently (I didn't count), more than a quarter of the text is essays which do not move the plot forward. The essay about Waterloo is the most egregious example.
Too bad that wasn't in the musical. Can you imagine Russell Crowe belting an essay on Waterloo?
Re: Ask HN: How to level up your technical writing?
#147Earlier quoted context omitted.
Once downloaded a copy of Hound of the Baskervilles, broken into chapters as separate files. Each chapter was almost exactly the same length, within a few hundred characters, showing that it had been serialized first and chapters were sized for publication.
I'm trying to remember if it was Dumas, but some French author was reputedly paid by the word, so all their dialogue is incredibly drawn out ("I have a question." "What is the question?" "It is, as you might expect from me, a simple question." "By all means, please, present me with the question, that I may resolve your puzzlement." ... etc.).
Having read the "Great Illustrated Classics" edition of Moby Dick as a kid, and watched the Gregory Peck film, I can confidently assert I NEVER want to read the whole thing.
Even those "condensed" versions had enormous swaths of nothing in them!
Re: Ask HN: How to level up your technical writing?
#148Earlier quoted context omitted.
I'm trying to remember if it was Dumas, but some French author was reputedly paid by the word, so all their dialogue is incredibly drawn out ("I have a question." "What is the question?" "It is, as you might expect from me, a simple question." "By all means, please, present me with the question, that I may resolve your puzzlement." ... etc.).
Many modern novels seem that way too. Not the elaborate dialog, but endless rambling descriptions. Historical novels are often big offenders. Like the author has done a ton of research, not a bad thing, but can't bear to leave any of it out, and there is no editor to say that's too much, people don't need to know how big the potato patch at the Palace of Versailles was.
Re: Ask HN: How to level up your technical writing?
#149Earlier quoted context omitted.
> Oh, and use an editor (the human kind, not the digital kind.) This is so important (IMNSHO). It's fairly obvious, that editors are becoming a "lost art." My mother was a scientific editor, and she was brutal (she edited some of my work). It's really hard to find fiction books, that are less than 500 pages. I read a story about Stephen King. Apparently, he hates being edited (most writers don't like it). When he was…
I can only read his short fiction with few exceptions. He got to the point where he would take 50 pages (exaggeration, but still...) to describe, I dunno, a room. Okay, so the room is important, but is it that important?
Re: Ask HN: How to level up your technical writing?
#150Tech writer here. The absolute, invariable first rule in tech writing is to know your audience. Understand not just their technical problems but take the time to empathize with why they have these problems in the first place. Tech writing isn't about documenting, it's about finding the best way to explain something to people so they can solve their problems. Oh, and use an editor (the human kind, not the digital kind…
Grammarly is still better than no editor.