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

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.

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"

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)

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

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.

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.

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.

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.

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

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.

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.

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

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

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

Haha this is brilliant.

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/

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.

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

Isn't that comma unnecessary?

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

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

[redacted]