Ask HN: How to level up your technical writing? • Hacker News Board

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

#61

Post by carapace » Sat, Jun 25, 2022, 1:47 PM UTC

ghaff wrote: post #49

fnord123 wrote: post #23

Strunk and White. To some it will be too obvious. But English speakers (especially English as a second language people) outside the US have often never heard of it.

Unfortunately, this is now apparently behind a sign-up wall but for a counterpoint: https://www.chronicle.com/article/50-years-of-stupid-grammar... "The Elements of Style does not deserve the enormous esteem in which it is held by American college graduates. Its advice ranges from limp platitudes to inconsistent nonsense. Its enormous influence has not improved American students’ grasp of English grammar; it has sign…

That criticism would hold more water if it were more well written.

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

#62

Post by coffeefirst » Sat, Jun 25, 2022, 1:58 PM UTC

Start writing short stories and essays about literally whatever is on your mind that day.

Every type of writing you practice makes you better at every other kind of writing. The part of your brain that learns to make fiction flow will do the exact same thing for complex technical documents.

Also, find someone you think is amazing at technical writing and ask them to sit down with you and revise something you wrote. Study what they want to change and why.

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

#63

Post by DoreenMichele » Sat, Jun 25, 2022, 2:01 PM UTC

Your HN handle is from 2016 and has 508 karma. You could probably learn a lot by trying to explain stuff here in comments and see if it clicks with folks.

Benefits: You get prompt feedback as to the quality of your writing. You may build a reputation.

Downside: That feedback may not exactly be sugar coated.

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

#64

Post by anon1094 » Sat, Jun 25, 2022, 2:02 PM UTC

3 recommendations:

  1. Write more.
  2. Write clearly.
  3. Know your audience.

We're writing for engineers, not for entertainment. Release a technical article every week.

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

#65

Post by mishftw » Sat, Jun 25, 2022, 2:03 PM UTC

When I left high school for college (to pursue engineering) I was quite envious of my friends in the liberal arts - they were assigned papers all the time and I had no outlet for writing (something I enjoyed quite a bit).

I have realized that written/technical communication is a great differentiator.

I journal every day but specifically to your question I would say just start writing.

Knowing your audience is key. I usually include an executive summary section at the top of any design document or product requirements document for a high level view of why people should care. Then I dive into a background or history to give context. At the end of the day it's a narrative and follows similar arcs - just with more direct prose and specific facts. I'll also drop this resource here from the Pragmatic Engineer newsletter. [0]

[0]: https://newsletter.pragmaticengineer.com/p/software-engineer...

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

#66

Post by lkxijlewlf » Sat, Jun 25, 2022, 2:08 PM UTC

ChrisMarshallNY wrote: post #30

marcpaq wrote: 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…

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

#67

Post by larsrc » Sat, Jun 25, 2022, 2:21 PM UTC

ChrisMarshallNY wrote: post #30

marcpaq wrote: 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…

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

That's not just him, it seems to happen to a lot of authors when they get famous. They get more clout and can push back on the editors, or the editors become afraid to cut too much, and suddenly you have bricks where half the words could be removed.

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

#68

Post by tpetry » Sat, Jun 25, 2022, 2:21 PM UTC

ghaff wrote: post #37

k__ wrote: post #33

Earlier quoted context omitted.

Grammarly is still better than no editor.

IMO not by much. I mean, it catches out and out errors which is something I guess. And it gives some generally applicable feedback about excessive use of passive voice, overly long sentences, etc. But for the most part it doesn't really improve your writing in terms of structure, clarity, etc.

I always get the feeling that grammarly adds to much commas. And so many of the sentence rewriting suggestions just provide glibberish.

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

#69

Post by [deleted] » Sat, Jun 25, 2022, 2:24 PM UTC

[deleted]

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

#70

Post by larsrc » Sat, Jun 25, 2022, 2:28 PM UTC

Lots of good advice already (except there are better sources for writing style advice than Strunk & White). Here's one I and my linguist wife like:

Write on paper first.

Paper is more immediate and has fewer distractions, fewer ways to go back and edit at once, and leaves a bit more time to think. It doesn't require looking at a screen, which you probably do enough of already.

Sure, typing it up is an extra step, but it can be a good editing step. Having edited (to the best of my ability) some of my wife's writings, I have been able to correctly guess when she wrote directly into the computer simply by the writing being less coherent.