How to write technical posts so people will read them (2019)

https://reasonablypolymorphic.com/blog/writing-technical-posts/

by benhoyt • 6 years ago

257 54 6 years ago

First advice if you want to be read is to write about something that (many) people are interested in, that's mostly popular and trendy technologies for a tech blog. A good old rant on javascript or kubernetes is likely to do well and take over HN/reddit/twitter, whereas an article on clojure not so much.

I've got some nice articles about obscure tools that are doing really well, or really bad depending on perspective. First google results in their respective keywords. They get a whole 10 viewers a day sometimes! I thought this was disappointing but I came to accept that is everybody on the planet who cared about that subject.

DanielBMarkham• 6 years ago

As a writer, I think you also need to decide: are you writing to be read, or to help people? They're not the same thing. If you're writing to be read, you'll go for low-hanging fruit, say things most people would agree with, and show a passion that matches whatever the popular passion already is. If you're writing to help people, you may have various messages that are unpopular or don't appeal to the average coder.

Unstated here, but also important, is that fame brings fame. There are a lot of folks writing schlock but are quite popular because they're the people that everybody thinks are supposed to be popular.

TacoSteemers2• 6 years ago

To be able to help people we also need to attract readers that our writing might be helpful for. I'm not sure how to solve for that. Should one try to share our writing mostly in niche communities?

I think feedback is good for improvement, in that sense it feels like a chicken and egg problem.

the_arun• 6 years ago

Writing is hard (Let alone tech writing). Even for good story tellers. Serializing complicated stuff to something everyone can understand is an art. Some people are gifted & excel. It is similar to why only few standup comedians are successful. Eg. Seinfeld.

kyleblarson• 6 years ago

Isn't that comma unnecessary?

unstatusthequo2• 6 years ago

And the capitalization. Do I want to take writing tips when the title is botched?

tedunangst• 6 years ago

Maybe you could make the extreme effort to click the link and read the title as it appears on the actual page.

Terretta2• 6 years ago

Clicking the link reveals an article with the title:

“How to Write Technical Posts (so people will read them)”

runxel2• 6 years ago

I would like to add presentation here.

Actually the very website has put me off to read more than a few sentences. If we talk about accessibility by contriving short sentences which are easy to read and grok, we should also mean accesibility in a visual way. The website uses nearly the full width of my display – which is frankly way too wide.

Now take a look at an article by Paul Graham. Dense content, but it's still easy to read, because it is visually well organized. Rule of thumb: ~70 characters per line.

uryga• 6 years ago

Rule of thumb: ~70 characters per line.

i wish HN followed that! i usually end up putting it in a narrow window (or emulate a narrow screen; Ctrl+Shift+M in Firefox) to make it easier to read.

tennineeight• 6 years ago

And I just realised why I prefer to read HN on mobile. The Hews app in particular has fantastic flow to churn giant multi-threaded conversations. The desktop website, in comparison feels like designed for reading every single comment.

runxel2• 6 years ago

Me too!

Thats's why I use Stylus in Firefox. I style most of the sites I visit (I really like dark mode...). What I did on HN was e.g. to apply `.comment { max-width: 35em; }`. That's a much better width!

AlwaysRock• 6 years ago

A buddy recently started a company based around helping companies write better software engineering blogs. Maybe interesting to some folks who want to explore this topic more: https://draft.dev/

hliyan• 6 years ago

I'm precisely the type of person this describes:

"...are likely to read only the headings and the first two sentences of a paragraph. If they’re convinced they know what you have to say, they’ll skip to the next paragraph."

It's a testament to the author's ability to follow his own advice that I actually managed to read most of the article without skipping.

unclesaamm• 6 years ago

This article talks about formatting and other superficial stylistic issues.

The main challenge of writing a technical post is deeper: who is your audience? And how much do you assume they already know?

The temptations are to take extremes: either you have to reexplain everything in the universe, or you assume you're talking to someone who already knows everything.

I've found this surprisingly hard to balance. In the end, though, I decided it's always better to err on the side of comprehensibility. This is true even for highly technical writing like scholarly articles.

One way that I've found works is to first write it out, stream of consciousness. Invariably this will be too technical. That will be obvious after waiting a day or two and revisiting it. Then build a bridge between where you are now and where the article is, with a more general introduction, and revise the body to flow with that new introduction. It's okay to push details to a supplement or appendix or footnote if necessary.

65536• 6 years ago

This article talks about formatting and other superficial stylistic issues.

On that note though, there is one thing that people have been doing for the past 5 or so years, maybe a bit more, with the formatting when they write online. In particular I see it often on Medium.com

They use blockquote to highlight some piece of their text. But the text in the blockquote is not a quote. Neither from elsewhere nor from their own text.

This annoys me.

AFAIK, blockquote has a history in the printed press of being used to catch your eye when you flick through a newspaper, so that you would want to buy the paper and read the article on that page. And the text in the blockquote was extracted from the text itself. Often from a part of it where a person that was interviewed said something that the editors found interesting. At least, that’s how I remember it.

Another type of use it is suitable for is to distinguish something quoted from elsewhere from the rest of the text.

But the way that it is being used now, it confuses and annoys my brain every time.

lemoncucumber• 6 years ago

You're thinking of pull quotes, which can be confusingly similar to block quotes but are a different thing:

It seems that many people (myself included) confuse blockquotes and pull quotes.
The main purpose of a blockquote is to separate a large section of text — quoted from an outside source — that is relevant to the source material at hand.
A pull quote is a section of the article pulled out of its context and repeated to give either emphasis, or to aid the reader in scanning the article.[0]

Unfortunately HTML doesn't provide a pull quote element so you have to make do with applying some CSS to a <blockquote>, or <p>, or whatever to get the desired visual effect.

[0] https://www.studiopress.com/how-to-use-block-quotes/

quest88• 6 years ago

I'll add to that the writers who bold many words throughout the article.

jedberg• 6 years ago

A lot of people don't seem to like to use the web for what it was invented for -- hyperlinking. The beauty of writing an article online is that if there is something that requires a lot of background, you can give a one sentence summary and then link to a whole page with details if the person needs that.

Lammy2• 6 years ago

And then that page will have a 50% chance of being unavailable after a year. I usually link to (creating, if necessary) a Wayback snapshot of any page instead.

pier252• 6 years ago

The main challenge of writing a technical post is deeper: who is your audience? And how much do you assume they already know?

It's impossible to write for everyone. So, you either write in a context which gives you a ballpark target, or you decide what your target is.

That's better IMO than trying to please as much people as possible which will completely dilute your communication.

greggman3• 6 years ago

I've found this extremely frustrating writing tutorials. Let's say I have 40 of them. Every few days someone will jump into #35 and complain they don't get it even though it lists right at the start that to understand it you need to read #21, #25, and #31. And #21 will say to understand first read #5, #6, #7 etc... But they'll skip all of that and then get upset that not everything was explained. It's very frustrating.

I don't think anyone would jump to chapter 35 of a textbook and be upset it requires reading previous chapters but in HTML they apparently do get upset about it all the time.

Lammy2• 6 years ago

Maybe you should call your posts chapters too?

StavrosK• 6 years ago

I wrote https://skorokithakis.github.io/expounder/ to help with this. I'm a mediocre writer but I think that it helps more than having a one-size-fits all approach.

unstatusthequo2• 6 years ago

[redacted]

Terretta2• 6 years ago

Clicking the link reveals an article with the title:

“How to Write Technical Posts (so people will read them)”

galacticaactual• 6 years ago

When writing technical posts, I've always used the mental model of explaining something to someone approximately two "technical rungs" below me in their career. It's qualitative and imprecise but the concept helps me scope how wide the explanation aperture needs to be for a topic.

gwbas1c• 6 years ago

Good skim for anyone who's posting to Hacker News and participating in Hacker News discussions.

People who spend lots of time reading have good heuristics for skipping lots of text. If you understand these heuristics, you can make it easy for people to find what they’re looking for. And remember: they’re looking for reasons to continue reading. ... They’re looking for what you’re trying to tell them, as opposed to what you’re actually saying.

I can't count how often I've come across a highly-ranked HN article and asked myself "what's the point" after 3-4 paragraphs. Then, the article has no headings, bold, callouts, ect, that would entice more reading.

At this point I flip over to the Hacker News discussion to see if anyone's summarized the point. Usually someone does, (and sometimes it entices me to continue reading.) Other times, it looks like someone just doesn't understand "And remember: they’re looking for reasons to continue reading"

MOTF• 6 years ago

As someone that writes a lot and publishes for public consumption I really appreciated your comment.

Sometimes as writers we overthink the process and lose sight of the entire purpose of writing ie: to communicate in a way that readers value. Oftentimes that means skipping the prose and getting to the point.

65103• 6 years ago

I find it interesting how clear the difference with books. A books reader can be expected to have some stickwithitness.

Minor49er2• 6 years ago

One thing I want to add: I've noticed in my own writing that I include a lot of run-on sentences. I also have some trouble with organizing my thoughts. To get around these problems, I make sure to take a break from writing to get out of the zone. Then I come back as a reader and start proofreading and editing my work. This approach has helped me to write much better posts.

dharmab• 6 years ago

I installed a screen reader to read my writing back to me the next day. Hearing my words helps me find confusing wording.

Minor49er2• 6 years ago

This is a great idea. I'm going to give this a try. Thank you.

tmaly• 6 years ago

His mention of people getting through the writing gave me a thought. Many blog writers follow the advice that Google like 1000+ word posts. Some people even go so far as writing 3000-5000 word posts just to get ranking in search engines. From a readers perspective, I do not want to read a really long post. I am strapped for time, and I just want to get at the little bits of information I need to answer my question. How do you feel about lengthy posts?

That quote at the bottom is usually attributed to Aristotle.

TacoSteemers2• 6 years ago

How do you feel about lengthy posts?

Hey, I'm not OP, but I was thinking about that earlier this week. I tend to read only the first paragraphs of lengthy posts. If the writing isn't pulling me in further, I stop reading.

For that reason I have put a four sentence short summary at the start of my latest post. If anyone considers the point I make there, but doesn't continue reading, it might already do good.

pier252• 6 years ago

Tell them what you’re going to tell them. Then tell them. Finally, tell them what you told them.

Haha this is brilliant.

65103• 6 years ago

Unknown = Aristotle.

In that video from Larry McEnerney linked above he says: Tell them what question they have the text is going to answer.

voortuckian• 6 years ago

This is clearer, more indepth, and longer: https://www.youtube.com/watch?v=aFwVf5a3pZM

But I found it more motivated me to change. (Chicago U, writing class for grad students)

zomglings• 6 years ago

I'm 15 minutes into this video and just had to pause to thank you.

This guy is fantastic. He has changed how I see the world.

Thank you.

just-ok• 6 years ago

Wow; I don’t think I’ve ever watched a hour-plus lecture recommended by an Internet stranger before today. Thank you for sharing this. I was compelled by zomglings’ review and the value (heh) was apparent by minute ~15 as promised. Reframing how I think about writing has me wanting to rewrite the thousand-odd pages I’ve published (blog posts, notes, etc.) over the past few years...

zjs• 6 years ago

Feedback about writing quality has been hard for me to address. This video clearly explains the difference between the way students learn to write and the way we should write in the "real world". The ideas are easy to apply and, in hindsight, embarrassingly obvious.

spekcular• 6 years ago

This is the best YouTube video I've watched in a long time. Thanks for posting it. (The same lecture from the previous year is also there, and though it overlaps a lot, also worth watching.)

sails• 6 years ago

I've been doing some "light technical" writing about data analytics systems. I've been adding metaphors to make it easier to read and skim. I'd appreciate any thoughts [1] as to how this might detract from the content or message.

I feel like I achieve both of the goals below, by taking time to justify why it is worth reading, and using interesting style to make it enjoyable to read and skim. I feel like this style might be useful in deeper technical posts [2], but I'm not sure if it still works.

two primary goals to focus on:
1. Provide strong, concise motivations for everything you want to talk about.
2. Make it easy to skim.

[1] https://groupby1.substack.com/p/data-as-a-utility-tool

[2] https://groupby1.substack.com/p/snowflake-field-notes

ulisesrmzroche• 6 years ago

Remember Why's Poignant Guide to Ruby? It's not all about skimming.

runningmike• 6 years ago

“focusing on why is going to be more valuable than on how.” imho the how is equally important. The how often makes the difference between solid advice or more general advice.

supernova87a• 6 years ago

I think one concept missing from the post is that good writing takes heavy thought on what to remove and not talk about.

Beginning developers or writers of technical information often just transcribe and document everything. In that, the emphasis of the writing is "flat". Everything is equally important. That is lazy thinking.

You encounter this in people doing standup summaries for their teams and just regurgitating everything on their minds, taking up people's time. Usually it means they haven't prepared in advance and thought through what they're going to say.

It takes actual work to distill that to "what things matter to other people?". "What details are important to mention, and not to mention?" Every word included takes away from another word that could be said. Which words are most important?

It takes actual work, understanding of the use cases, and thought, to turn flat documentation into perspective that people find useful. It means often, opinionated editing and writing from a point of view of, what's important (if it is not a pure reference work).

65103• 6 years ago

I write enormous walls of text really fast full of examples and detail, I move the sections around until I'm happy. Then I delete about 95% of it and rewrite 10%. I start above the text and eat what is written below while rewriting it. I always look at the end result and think, if only I really was that smart.

MaxBarraclough• 6 years ago

Sounds similar to math. A beautiful compact proof probably didn't start out that way.

suyash• 6 years ago

I talk about exactly this and more including how to tell stories both in writing and presentation to make your technical content more engaging. Feel free to subscribe if that interests you: http://tinyletter.com/suyash

peterwwillis• 6 years ago

# Tips for Writing Documents

## About

This comment explains what I know about writing docs to make them easier to understand. A succinct paragraph at the top should state what the rest of the document will cover. Don't create a document with random "stuff" in it and not explain what that "stuff" is at the beginning.

## Header Sections

Break up your document into discrete sections. They can be categories, a series of steps, etc. These headers break up the page into logical chunks of information. The header title pre-loads your brain to receive the following information, and makes it easier to skim. These header sections become a Table of Contents later.

## Grouping Information

A leading sentence groups a set of correlated bullet points:

  - bullet points are useful visual indicators
  - they break up important points
  - they are very easy to absorb individually

Call out the major steps needed to perform an action.

  Step 1. Figure out the major parts of your instructions
  Step 2. Break up instruction into discrete steps
          - Provide sub-grouping for complex steps
  Step 3. If additional steps are required but not included here, call out 
          that they are necessary and where to find further information.

## Adding Emphasis

Using specific emphasis can help to underscore __unique information__ and make it easier to find specific information ON THE PAGE. It also helps break up concepts visually, making it Easier To Read.

Emphasis makes skimming easier. Skimmability makes it more likely people will absorb the information you want them to.

## Be descriptive

Using extra, otherwise unnecessary words can "de-compress" a concept so that it takes less brain power to understand what the words mean. It may not be beautiful prose, but it will be easier to understand to more people.

Don't be afraid to break a paragraph up to make it easier to read. One idea spread over many paragraphs is a lot easier to understand than trying to pack it all into one.

## Don't make assumptions

Probably more than one person will be reading your document. We all have different life experiences and will interpret it slightly differently. Ask yourself if all your readers know everything you know. Probably not, or they wouldn't be reading your doc!

Before you dig into something complicated, think about what information is necessary to understand it. List the pre-requisite knowledge needed to grok the next information. Provide background information for concepts you haven't covered yet, and refer to other documents when possible.

## Use Graphics

Complex concepts can be understood easier when presented visually. If it would take you two pages to explain something that a simple diagram or flow chart can express, start with the visual. Use the text to explain details that the diagram doesn't show.

# Edit, edit, edit

Drafts are important. Constantly revise your document as you write it. Review it and see if re-writing or re-organizing sections makes it easier to read. Read it from the beginning and see whether your edits have stopped making sense, and edit again.

Documents get better when you revisit them later and solicit feedback. A fresh perspective is always good.

warrenm• 6 years ago

TL;DR: you need a hook

This is something all writers should know

Why it took 4 pages to explain this, I don't know

Reading it about return on investment - you have to convince me early that it will be worth my time investment to read what you wrote

That's what the hook is for

Further references:

- https://bid4papers.com/blog/hook-for-essay - https://writing.stackexchange.com/a/33505/1317

How to write technical posts so people will read them (2019)

Related Stories