How to write technical posts so people will read them (2019)(reasonablypolymorphic.com)
reasonablypolymorphic.com
How to write technical posts so people will read them (2019)
https://reasonablypolymorphic.com/blog/writing-technical-posts/
57 comments
> 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.
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.
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/
> 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/
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.)
(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.)
I'll add to that the writers who bold many words throughout the article.
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.
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.
Rather than linking to another page, you can link elsewhere within the same page, using fragment URI-refs. Write your asides as long footnotes, and then link to the footnotes.
(Or, go further, and split your article into a set of related articles all on the same page, with one “main” article and then several “supporting” articles that you can read or ignore. A non-editable Tiddlywiki, basically.)
(Or you could go even further and make your article into a Twine game. But that’s just getting silly.)
(Or, go further, and split your article into a set of related articles all on the same page, with one “main” article and then several “supporting” articles that you can read or ignore. A non-editable Tiddlywiki, basically.)
(Or you could go even further and make your article into a Twine game. But that’s just getting silly.)
https://developer.mozilla.org/docs/Web/HTML/Element/aside
Consider using this mark-up and displaying the document portion in the margin, or as a float inset into the article. Footnotes inhibit the flow of reading because they require navigating away from where the reader's eyes were.
Consider using this mark-up and displaying the document portion in the margin, or as a float inset into the article. Footnotes inhibit the flow of reading because they require navigating away from where the reader's eyes were.
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.
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.
Maybe you should call your posts chapters too?
> 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.
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.
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.
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"
> 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"
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.
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.
I find it interesting how clear the difference with books. A books reader can be expected to have some stickwithitness.
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)
But I found it more motivated me to change. (Chicago U, writing class for grad students)
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.
This guy is fantastic. He has changed how I see the world.
Thank you.
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...
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.
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.)
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).
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 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.
Sounds similar to math. A beautiful compact proof probably didn't start out that way.
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.
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.
> 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.
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.
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.
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!
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!
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.
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.
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.
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.
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.
I think feedback is good for improvement, in that sense it feels like a chicken and egg problem.
[deleted]
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 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.
"...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.
That quote at the bottom is usually attributed to Aristotle.
> 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.
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.
“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
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.
[deleted]
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
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?
And the capitalization. Do I want to take writing tips when the title is botched?
Maybe you could make the extreme effort to click the link and read the title as it appears on the actual page.
# 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:
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.
## 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
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.
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]
Clicking the link reveals an article with the title:
“How to Write Technical Posts (so people will read them)”
“How to Write Technical Posts (so people will read them)”
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.