Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Ask HN: How to level up your technical writing?

news.ycombinator.com

Post reply on HN
Print view View original

31–40 of 162 posts

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

#31

Post by vnorilo »

sateesh wrote: post #27

I have a bit of an unusual suggestion. One thig that had helped me is reading "The Economist". Their style is succinct, doesn't make lot of assumptions about reader's prior knowledge. Many a times I have read articles in it about many of the areas which I am barely familiar with and come out better informed. Probably that's what one would strive for in technical documentation.

Their style guide [1] is one of my references when trying to improve my own writing.

While my professional writing has been mostly academic, I find the progression is similar to tech writing.

First you learn to show your erudition and command of the ingroup speech.

Then, if you have a genuine desire to communicate, you progress to simpler yet precise language, stop using the big words when not necessary (often, they are just signaling and gatekeeping) and develop empathy for and understanding of the audience.

1: https://cdn.static-economist.com/sites/default/files/store/S...

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

#32

Post by klodolph »

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

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

#33

Post by k__ »

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…

Grammarly is still better than no editor.

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

#34

Post by O__________O »

To be a good technical writer, you must understand who needs what and why, then figure out how to solve that the best way based on the context.

Anyone looking for a good system of producing documentation should check out:

https://documentation.divio.com/

Which has a 30-min presentation:

https://m.youtube.com/watch?v=t4vKPhjcMZg

Prior HN posts on the system are here:

https://hn.algolia.com/?q=https%3A%2F%2Fdocumentation.divio....

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

#36

Post by tetha »

It's not strictly from the technical writing corner, but I've learned a lot from the book "The Craft of Scientific Writing" by Micheal Allay. It's more geared towards scientific papers, but I've found the style papers are structured to be a very useful starting point for design documents and runbooks. I tend to start with something like that, and adjust it according to the audience.

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

#37

Post by ghaff »

k__ wrote: post #33
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…

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.

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

#39

Post by remoquete »

phendrenad2 wrote: post #17

My advice: read lots of old, old technical documentation. For some reason, technical writing became much worse after 1990 or so. Probably something to do with the commoditization of tech.

Related: https://news.ycombinator.com/item?id=30365800
Post reply on HN