banner
yono

yono

哈喽~欢迎光临
follow
github
HomeArchivesMix Space

Stupid Writing

8
AI Translation
This post is translated from Chinese into English through AI.View Original
AI-generated summary
The text discusses the challenges of effective communication, particularly in technical writing. It emphasizes that both low and high levels of knowledge can hinder expression—low knowledge may lead to vague communication, while high knowledge can result in jargon that confuses lay readers. The author reflects on their own writing, noting that many technical posts assume a beginner audience, often providing step-by-step tutorials. However, some articles require prior knowledge that may not be adequately explained, leaving readers confused. The author believes that good writing should serve as a one-stop solution for readers, allowing them to grasp complex topics without needing extensive background knowledge. They advocate for using hyperlinks to provide additional context without overwhelming the main text. The author acknowledges the difficulty of producing such comprehensive articles and the lack of immediate rewards for doing so. Ultimately, they argue for clarity and precision in technical writing, contrasting it with poetry, which can be open to interpretation. The goal is to make technical concepts accessible, even to those with limited knowledge.

When we want to express something, we are limited by our own level of knowledge. A low level of knowledge can lead to problems—expressions that are not accurate and vague can avoid errors, and many people use this method to evade mistakes. A high level of knowledge can also bring problems—jargon everywhere makes it hard for outsiders to understand, and the relevant knowledge may not be in the reader's mind, making it difficult for ordinary people to comprehend the expression.

All expressions have their audience. Even simple text requires the audience to be literate and have basic reading skills; toddlers can only understand expressions in picture books. Who is the audience for our writing? Are technical articles meant for people with a higher level than the author?

Zhihu#

Today, while browsing Zhihu, I saw a question Why do parents get anxious when explaining problems to their children? - Zhihu.

Because you like to use hyperlinks when you speak, you have a library in your mind, and the information is called from that library, but the child does not have this library, so when you send a bunch of hyperlinks, they all fail to call, and what the child hears for a long time is 404 not found.

Words and language themselves are a kind of hyperlink; at least the reader needs to understand the meaning of the words, for example, ==hyperlink== is a somewhat uncommon term. However, we cannot insert a detailed explanation of ==hyperlink== in a lengthy discussion here. Therefore, the audience of this article should have at least some experience in surfing the internet, and these common terms in our eyes do not need detailed explanations.

It is necessary to judge what kind of knowledge the audience possesses before writing to avoid situations where readers feel confused or find the writing tedious and meaningless halfway through.

My Writing#

Looking back now, my technical blog posts often assume that the readers are beginners in a certain technical field, and most blog posts are step-by-step tutorials where clicking through will always lead to the expected phenomena. Without methodological support, I have unconsciously focused on the reader's level issue. Proud (‾◡◝)

However, there are still some slightly deeper blog posts that require readers to have a certain level of knowledge 1, which requires a lot of prerequisite knowledge that many readers do not possess, but there are no relevant explanations, leading readers to search for scattered information.

Arrogance and Laziness#

The text of books is limited by length, often focusing on solving one problem throughout the entire book, while the prerequisite technology is briefly mentioned.

I believe a good article is a one-stop solution; if the problem is at the level of 2, then readers who are not yet at the entry level to Heart Turns Hands should be able to solve the problem through one article.

Thanks to the presentation in software form, an article can focus on describing the overall process, with prerequisite knowledge and details inserted as hyperlinks in certain paragraphs.

Writing such a good article is time-consuming and labor-intensive, and there is little benefit; I cannot truly hold myself to this standard.

But I believe that this ultimate standard is not a problem. Not doing so is like writing code without comments; if the person reading the code can easily understand it without barriers, then the reader's level may be much higher than that of the writer.

For technical writing, I do not think "like poetry" is a good evaluation; poetry is a concise and powerful cultural hyperlink, with interpretations varying from person to person, and its connotations are rich and complex. But for technology, my requirement is to describe as accurately as possible; only through countless precise components can a precise technical system be pieced together, and it is best to avoid controversies and side effects that leave people scratching their heads.

Clumsy Writing#

Treat yourself as a clumsy author and ruthlessly squeeze yourself.

Treat the reader as a clumsy reader and write something that even a monkey can understand, like Shakespeare.

This article is synchronized and updated by Mix Space to xLog. The original link is https://www.yono233.cn/posts/white/25_4_3_BungleW

Footnotes#

  1.  Fire Dragon Fruit Talks Movies invented four levels of Mahjong: Building Roots, Heart Turns Hands, Upper Level, and Ghosts and Gods, with levels gradually increasing. ↩ ↩

  2.  Fire Dragon Fruit Talks Movies invented four levels of Mahjong: Building Roots, Heart Turns Hands, Upper Level, and Ghosts and Gods, with levels gradually increasing. ↩ ↩

Loading...
Ownership of this post data is guaranteed by blockchain and smart contracts to the creator alone.