Live data from Hacker News

Ask HN: How to level up your technical writing?

news.ycombinator.com

141–150 of 162 posts

Re: Ask HN: How to level up your technical writing?

#141
This may be helpful: https://writing.stackexchange.com/a/33505/1317

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

Re: Ask HN: How to level up your technical writing?

#142

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

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

#143

Earlier 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…

>A good editor gets to know your weaknesses and corrects them gently.

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?

#144

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

I don't especially care whether you choose the Oxford comma, or not.

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?

#145
post #137

Earlier 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…

>Even the best authors need an editor.

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?

#146

Earlier 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?

I would pay good money to watch that!

Re: Ask HN: How to level up your technical writing?

#147
post #120

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

That's one of the ongoing theories as to why Moby Dick was so long ... not merely to accentuate the 99.99% bordedom of whaling (with the 0.01% of "excitement"), but because he'd get paid better if it were longer

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?

#148
post #134

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

while not a big Western fan, I do find Louis L'Amour's compact descriptive format to be intensely engaging

Re: Ask HN: How to level up your technical writing?

#149

Earlier 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?

I've never read King, but do recall the hilarity of Goldman's "The Princess Bride: S. Morgenstern's Classic Tale of True Love and High Adventure, The "Good Parts" Version" ""editorial' comments throughout ... like "with this and that, we move to chapter 4"

Re: Ask HN: How to level up your technical writing?

#150
post #33
post #24

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

I still use Grammarly in my browser, but had to turn it off on my phone and elsewhere ... it's a great idea of a tool ... but ends up being unworkable too often :(
Post reply on HN