Zhihu

Today, while browsing Zhihu, I came across a question: Why do parents get so frustrated helping their kids with homework? - Zhihu.

Because you talk in hyperlinks. You have a library in your head—all of it is called from that library—but the child doesn’t have this library. You send over a pile of hyperlinks and every call fails. You talk for ages, and all the child hears is 404 not found.

Text and language are themselves hyperlinks. At the very least, readers need to understand what words mean; for example, hyperlink is not that common a word. But of course we can’t insert a long, detailed explanation of hyperlink right here. So the audience for this article is assumed to have at least basic internet-surfing experience; words we consider common don’t need elaboration.

To stop readers from quitting halfway because they feel lost, or finding the article wordy and pointless midway through, it’s necessary to judge what knowledge the audience has before writing.

My writing

Looking back, my technical posts often assume the reader is a beginner in some technical field. Most are hand-holding tutorials—click through step by step and the expected result always shows up. Even before I had a methodology to rely on, I was already unconsciously paying attention to the reader’s level. So proud (‾◡◝)

Still, there are some slightly deeper posts that require readers to be at the ^{[^筑根]} level. They need plenty of prerequisite knowledge the reader doesn’t have, but with no explanations provided, the reader ends up searching through messy, scattered material.

Arrogance and laziness

Print is constrained by length; a whole book can usually focus on only one problem, and prerequisite techniques are passed over in a few words.

I think a good article is a one-stop solution. If the problem is at the skilled-practitioner level, then readers from uninitiated to skilled practitioner should be able to solve it with one article.

Thanks to the digital medium, an article can focus on describing the overall workflow, while prerequisite knowledge and details can be inserted into certain paragraphs as hyperlinks.

Writing such a good article takes time and effort, and there isn’t much reward, so I can’t truly hold myself to that standard.

But I think this ultimate standard is right. Not doing it is like writing code without comments—if readers can understand the code without any trouble, their level is much higher than the writer’s.

For technical writing, I don’t think “reads like poetry” is good praise. Poetry is a terse, powerful cultural hyperlink; it can be read a thousand different ways, and its meaning is rich and intricate. For technical writing, though, I want the description to be as precise as possible: assemble a precise technical system from countless precise parts, ideally without controversies or side effects that make people scratch their heads.

Self-Determination Theory (SDT)

I believe authors who publish articles for free always want readers to learn something from them, and they surely aren’t twisted enough to write just to show off. From the reader’s point of view, Self-Determination Theory (SDT) may help us write in a more scientific way.

Where does the reader’s agency lie when facing an article? Self-determination theory attributes the root of agency in any action to 1. competence, 2. relatedness, and 3. autonomy. So here are some undebated claims about reading blogs.

Competence is the confidence an individual feels in displaying skill or effectiveness in an action; relatedness is the degree to which an individual feels recognized or cared for by a group; autonomy is the degree of freedom an individual feels in actions and decisions.

When it comes to reading blogs, autonomy is maxed out. Given how little exposure personal blogs get these days, I think anyone still running one in this era is part of a small circle of blog friends, so relatedness isn’t a concern either. The long-winded writing style of this article can be seen as a targeted way to improve readers’ sense of competence.

Dumb Writing

In real engineering practice, we often take technical “shortcuts” and accumulate technical debt. “Dumb writing,” on the other hand, lets people step away from the engineering side and focus on the technology itself, noticing more details. For the writer, it also clears away some “technical debt” to a certain extent.