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.
> 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.
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.
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.
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"
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.
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).
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.
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.
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.
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.
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.
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.
"...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.
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.
[+] [-] unclesaamm|5 years ago|reply
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|5 years ago|reply
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.
[+] [-] jedberg|5 years ago|reply
[+] [-] greggman3|5 years ago|reply
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.
[+] [-] pier25|5 years ago|reply
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.
[+] [-] StavrosK|5 years ago|reply
[+] [-] gwbas1c|5 years ago|reply
> 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|5 years ago|reply
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.
[+] [-] voortuckian|5 years ago|reply
But I found it more motivated me to change. (Chicago U, writing class for grad students)
[+] [-] zomglings|5 years ago|reply
This guy is fantastic. He has changed how I see the world.
Thank you.
[+] [-] just-ok|5 years ago|reply
[+] [-] zjs|5 years ago|reply
[+] [-] spekcular|5 years ago|reply
[+] [-] supernova87a|5 years ago|reply
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|5 years ago|reply
[+] [-] runxel|5 years ago|reply
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|5 years ago|reply
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.
[+] [-] galacticaactual|5 years ago|reply
[+] [-] user5994461|5 years ago|reply
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|5 years ago|reply
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.
[+] [-] unknown|5 years ago|reply
[deleted]
[+] [-] Minor49er|5 years ago|reply
[+] [-] dharmab|5 years ago|reply
[+] [-] sails|5 years ago|reply
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
[+] [-] hliyan|5 years ago|reply
"...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|5 years ago|reply
That quote at the bottom is usually attributed to Aristotle.
[+] [-] TacoSteemers|5 years ago|reply
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|5 years ago|reply
[+] [-] suyash|5 years ago|reply
[+] [-] pier25|5 years ago|reply
Haha this is brilliant.
[+] [-] 6510|5 years ago|reply
In that video from Larry McEnerney linked above he says: Tell them what question they have the text is going to answer.
[+] [-] AlwaysRock|5 years ago|reply
[+] [-] the_arun|5 years ago|reply
[+] [-] unknown|5 years ago|reply
[deleted]
[+] [-] warrenm|5 years ago|reply
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
[+] [-] kyleblarson|5 years ago|reply
[+] [-] unstatusthequo|5 years ago|reply