我把测试、代码和散文都放在一个 Markdown 文件里，再也不用往文档里复制代码了
Literate programming 将 Markdown 文件作为单一事实来源，使文档、测试和实现保持同步。以下是如何用三十行 Python 实现它。
你的文档、测试和代码是三份文件，讲着同一个故事，却讲得都很糟糕。 你在源码里更新了函数签名，忘了改 README 里的示例。一周后，新员工把过时的代码片段复制到了生产环境。你的测试文件仍然把旧的行为编码为预期结果。现在你有两个 bug 和一个文档工单。…
documentation
4 posts
你的 Claude 对话已经是文档了。只是它会在 12 小时后消失。
LLM 对话包含意图、被拒绝的替代方案以及可运行的代码。这正是文档应该包含的内容。以下是将 ephemeral chat 转换为持久、可搜索的文档，同时不丢失叙事的方法。
你花了 45 分钟和 Claude 设计一个 retry circuit。你解释了 failure modes，因为 exponential backoff 会掩盖 cascading pressure 而拒绝了它，确定了 token-bucket rate limiting with…
Donald Knuth希望程序读起来像文学作品。编译器另有打算。
Literate programming承诺代码应该首先为人类编写，其次才是为机器。四十年后，几乎没有人这样写。以下是软件文档化中最优雅的理念为何未能改变我们工作方式的原因。
1984年，Donald Knuth发表了一篇提出根本性反转的论文。程序不应该是为编译器编写、为人类添加注释的。它们应该被写作为人类的文学作品，编译器从中提取可执行部分。他称之为literate programming，并以这种方式构建了TeX。 这个想法很美。它在现代软件开发中也几乎完全缺席。…
你的架构图早就是谎言了
架构文档在你保存的那一刻就开始腐烂。以下是如何利用代码生成图表、ADR 和自动化架构测试来保持文档的诚实。
我在 wiki 里见过的每一张架构图都是错的。不是那种惊天动地的错，而是悄无声息、日积月累的错。标着 "Auth" 的服务六个月前就被拆成了三个微服务。标着 "sync call" 的箭头现在已通过队列变成了异步调用。标着 "PostgreSQL" 的数据库在一次紧急故障处理中被迁移到了别的系统，却没人更新那个方框。…