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

81–90 of 162 posts

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

#81

Post by Gaessaki »

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 in bullet points, followed by inserting any placeholders and captions for any graphics (e.g. charts or diagrams), and then finally I start rewriting my bullet points into proper sentences, expanding my examples, and adding any interstitial text necessary to make things flow.

Also, I see some comments on keeping things short and to the point. In general, I agree with this, but depending on the medium, sometimes it doesn’t hurt to inject a bit of personality into your writing. Technical writing can be dry at times, and this can deter engagement. Try to use concrete examples whenever possible or refer to other supporting texts.

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

#82

Post by raybb »

gnat wrote: post #16

Two things I recommend: the Google tech writing courses: https://developers.google.com/tech-writing And "Bugs in Writing", which I've been pressing into people's hands for twenty years now. https://www.amazon.com/BUGS-Writing-Revised-Guide-Debugging/...

Have you taken the Google tech writing course? Were there any big takeaways for you?

About a year or so ago I read through a bunch of that course and it seemed like it would be okay for someone who is new to writing in a business setting. But generally the summary was said: be concise as possible while still getting the message across to the appropriate audience.

Looking at it again, the "organizing large docs" is pretty good. https://developers.google.com/tech-writing/two/large-docs#pr...

"Choose a heading that describes the task your reader is working on. Avoid headings that rely on unfamiliar terminology or tools."

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

#83

Post by Gaessaki »

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…

Wanted to add that relying on an editor is absolutely key. It doesn’t necessarily have to be a professional, a friend or colleague with strong communication skills will do. Edit your own work mercilessly as well, but only after you’ve put your main thoughts down. After a night of intense drafting, put your text in a drawer and come back to it in a day or two.

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

#84

Post by jacksnipe »

mishftw wrote: post #65

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…

Couldn’t agree more that narrative is the key. If you’re telling a compelling story (which can look very different for different audiences), you kind of get the rest for free, because you will have the reader’s attention.

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

#85

Post by jacksnipe »

YeGoblynQueenne wrote: post #54
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…

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

While I see where you’re coming from re: The Three Body Problem Vs the rest of the series, the core ideas in the Dark Forest and Deaths End are so exciting that I can’t help but feel the rest of the story is a justification for exploring them.

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

#86

Post by nicbou »

MrPowers wrote: post #43

Blogging & measuring average time on page is a great way to see if you're able to write content that's relevant and engaging for readers. Average time on page should be at least 5 minutes for a blog post. Improving open source project READMEs and documentation is another great way to practice writing. I am writing an O'Reilly book now and having a professional editor will help you learn the common errors you're makin…

I disagree with using time on page as a metric. If you can answer the question in half the time, good for your readers.

In many cases, people want the tl;dr only, so I try to give them that first.

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

#87

Post by sealeck »

- read your writing aloud (it _really_ helps to improve it) when you review it

- just write and then edit - better to have written something (even if it's not great) and then make it better. Especially in writing perfect can be the enemy of good.

- step away - sometimes it helps to review your writing after maybe 1 hour or a day or a few days

- READ MORE - reading well written stuff really helps

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

#88

Post by jacksnipe »

All good writing is about narrative. What a compelling narrative means is different for a technical document and a mystery novel, but narrative is the bedrock.

So make sure that things are motivated, and try to not just tell the reader the facts, but take them on a journey such that they will wind up with the right facts AND the right mental model at the end of things.

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

#89

Post by captainkrtek »

A few pointers from my own experience (usually in the context of design or proposals):

- why does a document need to be written? Is it to be discussed, debated, just documentation? Let this drive what really needs to be written. Often I’ve seen design documents with lengthy sections on information that is already well agreed upon or commonly understood, just adds noise for the reader.

- consider the audience. Engineers may read a document and have specific prior context that can be omitted, whereas a product manager may get lost in too much technical detail. Tailor your document to your audience, and use the appendix for extra details if someone wants to dig in further.

- keep it brief. Focus on information required to get the necessary outcome and convey the information clearly. Starting with an outline of headers is helpful as well.

- think of good writing you’ve come across. It was likely clear and succinct enough. In my own writing I used to include every last detail to make sure the reader was the most informed about how I reached some conclusion, but then realized too much info becomes counterproductive and doesn’t focus the reader on what matters.

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

#90

Post by ghaff »

benreesman wrote: post #40

I have failed deeply and fundamentally as a technologist by not being able to explain the technology in plain language. I now regard it as a minimum bar that I can explain the broad outlines in plain language. Anyone who can’t is is a fucking fraud.

While I see where you're coming from, get deep enough into specialized concepts and a "plain language" explanation that assumes no prior knowledge is going to have to hand wave away a huge amount of detail and may not even be completely accurate in many respects. Yes, you can probably give an intelligent person the gist of what's going on, perhaps by analogy, but it may not really be an "explanation."
Post reply on HN