- 最有用的一条：开头别铺垫，先把结果说出来。
- 最能建立信任的一招：把自己判断错的地方写出来。
- 最容易被忽略的一点：排版不是装饰，是让别人能扫。
- 能上图表、代码框、折叠块的，就别堆成大段文字。
起因：我嫌自己写的东西有股机器味
写前两篇的时候，每次都读着别扭。句子挑不出错，但就是不像人话，像谁替我写了份说明书。
这个问题自己猜是猜不明白的。我干脆去看那些写了十几年博客的人是怎么写的，看他们的方法、也看他们的排版。
看了谁，各拿走什么
| 看谁 | 他强在哪 | 我拿走什么 |
|---|---|---|
| Julia Evans | 用手画的图讲系统，一张图顶一段话 | 配图要讲清机制，不做装饰 |
| Simon Willison | 每天记一条"今天学会的"，十分钟写完就发 | 短笔记也是正经文章，不用等大题目 |
| Dan Luu | 长短句交替，专门写自己错在哪 | 承认判断失误最值钱 |
| Netflix、Stripe、Cloudflare 的工程博客 | 标题里带结果，正文里带翻车 | 把结论前置，主动写失败 |
| 中文技术博客的排版规范 | 每段不超过五行、标题分级、代码块标语言 | 先把骨架立起来，再谈内容 |
看下来最大的意外是：这几个人风格差得很远，长度也差得很远，但都在同一件事上不偷懒——把"我为什么这么判断"写清楚。
结构上最大的变化：从"讲课"改成"讲一遍经过"
教程式的写法是背景、原理、示例、总结，四平八稳。问题是读完你记住的是方法，记不住是谁写的。
叙事式从一个具体现场切进去，读者跟着你走一遍。
拿我自己的第三篇举例。事实是一样的，换两种排法：
❌ 本文介绍博客搭建过程中遇到的问题及解决方案。
✅ 搭这个博客花了三个晚上，其中一半时间在排查跟博客本身无关的事。
第一句得等我讲完才知道有没有货。第二句你一眼就知道要不要往下读。
改了第一件事：把自己判断错的地方写出来
这是我原来最不敢写的地方。写完发现，它反而是全篇最有用的部分。
❌ 推送失败通常由网络问题导致。
✅ 我一开始认定是网络问题，重试了三次都一样。最后发现是环境里配的代理是死的。
第一句谁都能写。第二句只有真被卡过的人写得出来。
判断错了不是减分项
读者信的从来不是"你一直很对"，而是"你踩过这个坑，你知道坑在哪"。把错误的判断和后来怎么发现的都写下来，比只给结论有用得多。
改了第二件事：能用图表、代码框、折叠块的，就别用大段文字
排版不是把东西弄好看，是让人能扫。我给自己定了几条对应关系：
| 要写的内容 | 用什么形式 |
|---|---|
| 几个方案的取舍 | 表格，一行一个方案 |
| 一段代码、一条命令 | 代码块，标上语言和文件名 |
| 一条流程、一条链路 | 配图 |
| 会打断主线、但有人想看的细节 | 折叠块，想看的自己展开 |
| 一句希望读者记住的话 | 提示块 |
光这一段说完没什么感觉，得能上手用。所以我把站点也改了：
- 文章开头加快览卡片，赶时间的人看完这一块就够了。
- 文章列表标上阅读时长，点之前知道要花几分钟。
- 正文支持提示块和折叠块，主线和细节分开。
- 代码块支持行高亮和删改标注，讲"从这块改成那块"的时候，不用再拿文字描述。
- 正文能插配图，讲链路和结构的时候比画表格清楚。
这些是怎么实现的
没有装任何新插件，全是 Markdown 自带的写法：
- 提示块：
::: tip 标题开头，:::结尾 - 折叠块：
::: details 标题，外面默认收起 - 代码行高亮：在行尾加
// [!code ++]（新增）或// [!code --]（删掉） - 代码块标文件名：在语言后面接
:文件名 - 配图：图片放到
docs/public/下面，正文里按路径引用
不引新依赖是刻意的。加一个插件就多一处会崩的地方，这些写法已经够用。
也顺手改了排版参数
查了一圈中文排版的说法，几个数反复出现：正文 16 到 18 像素，行高是字号的 1.6 到 1.8 倍，每行大概三十个汉字，段落之间的空隙要大于行与行之间的空隙。还有两条反直觉的：别用纯黑字，也别用纯白底，屏幕上会显得生硬。
我按这些调了正文的行高、段落间距和标题间距。改完最直观的变化是，一屏里的字少了，但读起来不累。
三条我自己定的规矩
看再多别人的方法，落到最后就是几条能执行的检查：
- 删掉署名还成立的文章，就是通用教程。 得往里补自己的东西：具体环境、具体失败、具体判断。
- 每段问一遍：这段换个 AI 也能写吗？ 能，就删掉。
- 结尾不总结。 落到具体的一步，或者一句短的判断，别写"总而言之"。
下一步
把这几条规矩写进那个"对话转博客"的流程里，以后每篇写完都按它过一遍。
规矩是要改的。等写到十几篇，再回来看哪几条其实没必要，哪几条当时该更狠一点。