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

101–110 of 162 posts

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

#101

Post by delecti »

As a first step, try and pay attention to things that annoy or frustrate you about other technical writing, and don't do those things.

I also try to assume my audience is a moron. Not because they are, but because any time you're doing technical writing, you presumably know more than them. Force yourself to not assume things are obvious just because you're familiar with them. IMO it's better for technical writing to be a tiny bit patronizing than to be lacking in vital detail. One specific example here is to either define any acronym before using it, include a glossary, or both.

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

#103

Post by SKILNER »

Someone else mentioned Strunk and White's Elements of Style, but in the true spirit of that book let me just cut to the chase and say, "omit needless words."

Our brains only have so much space in them so you only get to cram a small number of words into someone else's brain; make them the most productive words possible.

When writing, it's harder to remove words than write them.

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

#105

Post by Brystephor »

Gaessaki wrote: post #81

Lots of great advice here. One piece of advice I got from my publisher when authoring a technical book was to first break down what I was going write into headings and subheadings, and if possible, into sub-subheadings. Then review that to see if your flow is coherent and whether there are sections that are missing, or could be extracted into another text. Personally, my process after this is to express my thoughts i…

> Also, I see some comments on keeping things short and to the point

I think this is true. Another way of saying it might be to write things intentionally and make sure each sentence contributes to a goal. You can have humor and personality in the paper, but make sure you don't have filler or meaningless words that you're just writing off as personality.

I love when a document is easy to read and is thorough.

Side rant: I hate when people use an acronym in a document and never state what the acronym stands for. Take the extra 10 seconds and type it out the first time you use it with the acronym version in parentheses directly after.

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

#106

Post by rawgabbit »

I found the Hemingway style of getting to the point in simple English is the best way to get my point across. There are several apps that will help you write like Hemingway.

Get to the point. Usually in the first two paragraphs. The entire meat of a memo or chapter is on one page. The rest of the memo or chapter is supporting material with examples, clarifications, diagrams, and context showing how this idea relates to a different idea.

In meetings, I usually present only the first page or one diagram that summarizes the entire memo. I usually tell people to read the whole thing if they want more details.

I am also in the habit of sharing my drafts with a lot of people so they know what I am up to. By the time it’s completed the audience has probably already seen it twice . This helps with buy-in. As I have already met with people who have concerns or objections.

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

#107

Post by Gaessaki »

Brystephor wrote: post #105
Gaessaki wrote: post #81

Lots of great advice here. One piece of advice I got from my publisher when authoring a technical book was to first break down what I was going write into headings and subheadings, and if possible, into sub-subheadings. Then review that to see if your flow is coherent and whether there are sections that are missing, or could be extracted into another text. Personally, my process after this is to express my thoughts i…

> Also, I see some comments on keeping things short and to the point I think this is true. Another way of saying it might be to write things intentionally and make sure each sentence contributes to a goal. You can have humor and personality in the paper, but make sure you don't have filler or meaningless words that you're just writing off as personality. I love when a document is easy to read and is thorough. Side ra…

I think you phrased it well. The distinction I wanted to make is that it's more about clarity of thought than absolute brevity.

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

#108

Post by no_identd »

I have a whole Twitter thread on that, here:

https://twitter.com/no_identd/status/1220913617408864257

Prompted by my discovery of this book:

https://link.springer.com/book/10.1007/978-3-030-10756-7 "A Math-Based Writing System for Engineers: Sentence Algebra & Document Algorithms", by Brad Henderson

Edit:

Altmetrics just revealed to me that apparently a cheesy corporate marketing video for it exists:

https://youtu.be/X9vQoadsQ1I

Amazing.

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

#109

Post by ayewo »

Lots of solid advice already.

If you are up for it, you could try moonlighting as a writer for technical content marketing agencies. You get paid on the side, while also subjecting your writing to editorial criticism until it is ready for publication.

https://draft.dev/write

https://contentlab.io/writeforus/

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

#110

Post by no_identd »

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.

Not really:

https://web.archive.org/web/20170816111301/http://serenity-s...

https://web.archive.org/web/20170619192710/http://www.sereni...

Too bad Serenity Software appears AWOL.

Post reply on HN