
How to write technical posts so people will read them (2019) - benhoyt
https://reasonablypolymorphic.com/blog/writing-technical-posts/
======
unclesaamm
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
> 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
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/](https://www.studiopress.com/how-to-use-block-quotes/)

~~~
derefr
I think a pull-quote _might_ be one of the intended uses of <aside>.

(Though really, I don’t think HTML “likes“ pull-quotes — they’re a
denormalization of the information conveyed by the markup. The ideal from
WHATWG’s perspective would likely be some sort of intra-document transclusion
reference, such that the pull-quote could “sample” the text out of where it
already is on the page, without mirroring it.)

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

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

------
voortuckian
This is clearer, more indepth, and longer:
[https://www.youtube.com/watch?v=aFwVf5a3pZM](https://www.youtube.com/watch?v=aFwVf5a3pZM)

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

~~~
zomglings
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.

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

~~~
6510
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
Sounds similar to math. A beautiful compact proof probably didn't start out
that way.

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

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

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

~~~
TacoSteemers
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.

------
Minor49er
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
I installed a screen reader to read my writing back to me the next day.
Hearing my words helps me find confusing wording.

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

------
sails
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](https://groupby1.substack.com/p/data-as-a-utility-tool)

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

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

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

~~~
TacoSteemers
> 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.

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

------
suyash
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](http://tinyletter.com/suyash)

------
pier25
> _Tell them what you’re going to tell them. Then tell them. Finally, tell
> them what you told them._

Haha this is brilliant.

~~~
6510
Unknown = Aristotle.

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

------
Taylor_OD
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/](https://draft.dev/)

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

------
warrenm
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://bid4papers.com/blog/hook-for-essay) \-
[https://writing.stackexchange.com/a/33505/1317](https://writing.stackexchange.com/a/33505/1317)

------
kyleblarson
Isn't that comma unnecessary?

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

~~~
Terretta
Clicking the link reveals an article with the title:

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

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

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

------
unstatusthequo
[redacted]

~~~
Terretta
Clicking the link reveals an article with the title:

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

