这周更新还挺勤的，于是周刊的内容就变少了，合情合理。

Sooner or later, you’ll find out

I live in a pattern of breakdowns

You’ll bend to my silence, it’s so loud

And then you’ll lose me to the crowd

分析正确与否，问题依旧存在

📜

作者观察到，当有人指出问题时，其他人可能会试图解释问题背后的原因，然后，人们就理所应当地觉得问题被合理化了。可是，无论原因是什么，问题依旧是问题。坏的问题不会因为一开始的那个人的分析错了就不坏了。比方说，有人读到一篇文章的标题和文章内容毫无关联，此时有人解释「你知道标题很多时候不是作者写的吗？是他们的编辑写的标题」，然而无论标题是谁写的，标题都和原文无关啊（而且作者表示，他向作者指出标题问题，往往都会得到回应，他们是能和编辑沟通的）。

问题不会因为正确的分析就变得合理，不过人们好像理所当然地觉得，问题若是有了清晰的原因，搞出问题的人就没有责任，不该被责备，也不需要改变了。

另一个层次的例子是，当有人指出问题，负责的人解释了问题的缘由，而提出者却说：“噢，那也不是借口啊。”事实是，负责人从来没说过要用原因为自己开脱，更有利于解决问题的讨论方式是：我们了解问题发生的原因了，接下来要怎么改进和预防？

文档写给谁看？

📜

The Rust community doesn’t want beginners to learn Rust — it wants advanced programmers to learn Rust, which could even be fatal for the language in the long run.

Rust 社区根本不想让初学者学 Rust——他们想让高级程序员学 Rust。长期而言，对这门语言来说是致命的。

这不是长文，仅仅是作者近期事务繁忙、决定让自己慢下来的日志。他想要慢下来的其中一个原因是他在学 Rust，而这门语言的 文档 写得非常不利于入门。尽管我读 Rust 文档的时候（是的，我还试图学过这门语言……）不觉得特别难懂，但如果有更多详细的解释和例子当然是更好的。

我想之前读过另一篇博客文章（我找不到链接了），作者想写个简单的 Pastebin¹ 应用，顺带学一门新语言。他一开始选择了 Zig，却发现找不到方便理解的文档和教程，Zig 有 HTTP 相关的标准库，但他并不知道如何使用。这也和这门语言迭代太快有关系吧。之后他换成了 Go，发现了不少好用的教程，顺利完成了项目。

Go 语言各方面的工程思想都深得我心。Rob Pike 本人就说过「 Documentation is for users 」（文档为用户写），写文档不应该写「这个函数做什么」，而应该写「这个函数用来做什么」。那场演讲里还有一句话我印象深刻：

Don’t be afraid to explain things so that it makes sense.

不要害怕把事情解释清楚。

我近期还有一些个人的经历与这个话题相关。前几天项目验收，讲完之后老师（她是为数不多我比较尊敬的老师）问了我的职业规划，也鼓励我可以往运维支持和产品经理这两个方向走走看看，因为她觉得我的综合能力还不错。她说很多同学在讲项目时总是在讲细节，比如项目用的是什么数据库，某个单独的功能模块里能做的所有事情，很难让他建立起整体的印象。

其实我觉得自己讲得没有很顺，但的确，我是站在「老师作为评价者需要听到什么信息」的角度来讲述的，我先讲了最精炼的业务需求，再讲作为课程项目，这个系统的重难点是什么，然后再逐个介绍功能模块。这之后她几乎没有关于软件系统的问题问我（也有可能是她对项目本身不感兴趣吧）。

我想就和做任何事情一样，表达之前先捋清目的和听众的视角很重要。我发现很多工作无从下手的原因是，我不清楚对方想要什么。比方说写工作报告，报告上应该体现什么呢？这些数据和描述会被用作考核的依据吗？如果能明白目的就容易多了（最怕的就是布置任务的人自己也不知道目的是什么啊……）。

回到编程语言的文档这个话题。作者用《PHP: The Complete Reference》和 Rust 的官方文档对比，我其实觉得不太公平，前者也不是 PHP 的官方文档啊。Rust 文档的开头其实就把目的明确了。

This book assumes that you’ve written code in another programming language, but it doesn’t make any assumptions about which one. We’ve tried to make the material broadly accessible to those from a wide variety of programming backgrounds. We don’t spend a lot of time talking about what programming is or how to think about it. If you’re entirely new to programming, you would be better served by reading a book that specifically provides an introduction to programming.

简单来说，这本书假设读者已经用其他编程语言写过代码了，有基础的编程知识，本身就不是写给初学者的。他们只是在明确了目的之后才写出了对初学者来说有点难读的文档。作者最多可以批评他们的目的有问题，但我的看法是，如果真的希望从零开始，应该去找一本有着更详细的解释和更多例子的书。

目的或许是表达者/编写者和读者之间达成理解，最重要的因素之一。

r11y

把 HTML 转换为 Markdown 的库，可以用在任何网页上，能够去除掉非文本的其他元素。这个库用 Clojure 编写，同时也是一个命令行工具，可以在终端执行 r11y <url> 获取网页的 Markdown，用来写脚本或许很有用。

r11y 是 readability（可读性）的缩写，作者表示也可以读成：Oh, really?

访问： dazld/r11y

• 偷了伏枥的 着重号样式 来用。之前一直用 text-emphasis 实现着重号，但这会让有着重号的那一行的行高变高，看起来很奇怪，我一直没找到规避方案。这个基于 background-image 的方案看起来清爽多了。

  脚注的样式也修改了，字体调大了一些²，把数字编号从 1. 的格式换成了 [1]，貌似也更像纸质书里的脚注格式。此外，脚注原本被刻意设计成透明度很高，不引起注意，在需要阅读时将鼠标移动到上面才恢复不透明度；我意识到自己没有考虑到移动端，现在移动端的小屏幕上是完全不透明的。

• 因为某些我如今不想回忆的原因，某天早上一拳砸在健身垫上发泄愤怒，结果从那个时候开始直到现在小拇指都很痛，痛了两三天之后有好转，但我仍然觉得很不对劲，而且小拇指关节处有淤青。担心是骨折了，于是周六去挂了骨科的号。

  本来去了校医院，结果放射科没上班又跑隔壁医院，结果早上的号挂满了只能挂下午的，结果拍完片子要等结果，等完结果复诊又要排队…… 于是一天就这么过去了。

  还好没有骨折，可能是韧带拉伤了。谁能想到 618 的第一笔消费是 X 光和药钱呢？

• 我第一个比较正经的手摇磨豆机是 MAVO 的「巫师 2.0」，用了快两年，感觉还行，唯一的缺点是刻度不好调，我每次都会忘记它当下是什么刻度，必须归零再数格子。太麻烦了，所以我把它调整到一个不错的手冲通用刻度之后，就再也没有调整过（除非花大价钱买了精贵的豆子）。

  凑到还不错的优惠券之后，我就下单了同样是 MAVO 的「幻刺 Pro」，貌似圈内风评很好，也算是观望已久的产品。收到货之后基本满意，外置刻度真的太好用了，也方便我记录不同豆子适合的具体刻度数字，很大的体验提升。

  顺带一提，图上的手柄收纳是 3D 打印件，是单独购买的。闲置的时候手柄不会因为惯性转起来打到东西，个人感觉非常有用。

• 本周星露谷高光时刻。

  

  不过矿洞是朋友探的，我只是去领了个果子。

• 本周星露谷高光时刻 II。

  

  谢恩，你究竟有什么魅力……

• 我讨厌我的二十岁。