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

51–60 of 162 posts

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

#51

Post by setgree »

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…

> It's really hard to find fiction books, that are less than 500 pages.

To play editor for a moment — your sentence needs no comma, and it’s easy to find fiction books with fewer than 500 pages ;)

Was a clause omitted?

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

#52

Post by eatonphil »

Write consistently and spend time rereading what you write before/after you publish. Read out loud. Any time you find a confusing or unclear sentence, rework it. Get rid of unnecessary words.

I've been doing this for 1-3 blog posts per month for the last 4 years and I think my writing is decent now.

It didn't come naturally. I hated editing all my life until I took a course in college and realized I could actually write clearly if I just spent a little time reading and reworking what I wrote.

The only directly related book I'd recommend is On Writing Well.

I'd also suggest reading clear and simple authors like Hemingway (A Movable Feast), Antoine de Saint-Exupéry (Wind, Sand and Stars), and Beryl Markham (West with the Night).

But fundamentally: consistent practice, rereading, and editing.

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

#53

Post by pclmulqdq »

One thing: do it a lot. Set a time every day and practice. Some prompts to get you started:

1. Write a white paper on the application of a piece of OSS that you like.

2. Write a usage description for one of your one-off projects/scripts.

3. Write a technical paper about an algorithm you used in a specific instance.

4. Explain the solutions to classic interview problems (eg binary tree reversal) in written form.

5. At work, write up brief pitches for new product improvements you have.

In all cases, consider the audience and what needs to come across to accomplish your goal.

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

#54

Post by YeGoblynQueenne »

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…

> It's really hard to find fiction books, that are less than 500 pages.

For SF & F this seems to be a deliberate choice, from what I understand. This is from an iterview with Ted Chiang:

TC: I think the reaction varies, because science fiction is a more commercial genre. There are a lot more people in science fiction whose goal is to make a living from writing fiction by publishing one or more novels a year. And people who enter science fiction generally receive more messaging about fiction writing as a sole source of income than, say, people entering mainstream fiction. The messaging there is different: get an MFA, teach; it’s understood that your teaching position supports your career as a writer. For writers entering science fiction, that’s not really a thing yet. We’re maybe getting there, but the messaging they receive is mostly: Be very prolific.

https://culture.org/an-interview-with-ted-chiang/

>> As [Stephen King] got more and more famous, he started being able to bully his editors, to the point where his work is barely edited at all.

Yeah, I kinda noticed that too. I picked up a book of his and couldn't finish it because it felt like every episode in the story was written so that it took maybe ten, maybe fifty more pages than it really needed to. Extreme padding.

I think Liu Cixin also went through something similar. The Dark Forest was lean and mean. The next two books were progressively fatter and more verbose and full of aimless meandering. Though maybe that was an attempt to complete a trilogy to capitalise on the first book, if I'm more cynical.

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

#56

Post by [deleted] »

nonrandomstring wrote: post #48
ChrisMarshallNY wrote: post #30

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…

[deleted]

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

#57

Post by eatonphil »

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…

> It's really hard to find fiction books, that are less than 500 pages.

Allow me to introduce you to the myriad Maigret novels by George Simenon. :) They are my favorite filler books when I want something good at only 150-200 pages.

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

#59

Post by ducharmdev »

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…

I think many people write off empathy as being about warm and fuzzy feelings, and don't realize that it's a very useful skill that can be improved with practice.

The more effectively you can imagine perspectives other than your own, the more easily you can come up with creative solutions, communicate well, and overall just be a more pleasant person to be around.

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

#60

Post by danrl »

To more impactful convey they information, keep not only the audience in mind, but also how their brains will process that information. Then tailor content to make it easy for the receiving entity (brain) to process the information and store it effectively.

I found this guide helpful: https://www.knowledgeowl.com/home/three-tips-psychology-docu...

Post reply on HN