技术写作与文档2022joseph8th.github.io编辑精选
在 Emacs Org Mode 中撰写文学化的 API 文档
Writing Literate API Documentation in Emacs Org Mode
导读
这篇帖子介绍如何用 Emacs Org Mode 写「文学编程」式的 API 文档：把讲解文字、示例代码和可执行片段交织在同一份源文件里，再导出成文档，让说明与实现不再各写一遍。对写作者的价值在于，它示范了一种「叙述优先、代码可验证」的写作结构——文档不是事后补的说明书，而是和代码同步生长的正文。
可以直接用的写作要点
- 01
把示例代码直接嵌进正文并让它可执行、可导出，文档与实现同源，就不会写着写着过时。
- 02
先写给人读的叙述段落，再把代码块按讲解顺序拼装，读者是顺着你的思路理解 API，而不是查字典。
- 03
给每个项目维护一份 notes.org 式的工作日志，随手记下思路、命令、片段，素材自然积累成文档草稿。
- 04
把文档里的示例接进测试框架，文档的正确性变成可自动检查的东西，写作才有反馈回路。
HN 评论精选
实践者亲证：随手记录加可执行片段的工作日志，能显著提升产出效率。
我曾以为文学编程只是象牙塔里生出来的怪诞小众玩艺，换个土壤根本活不下来。直到遇见 org-mode——它真的改变世界，哪怕只为了 org mode 去装 Doom Emacs 也绝对值。我现在认真考虑用 org mode 做文学编程。它已经渗进我每个项目：每个项目都有个 notes.org，记录我做事时的意识流，把用过的代码和命令粘进去备查，效率翻了好几倍。推荐所有 vim 用户试一下 Doom Emacs，尤其 org mode 和 magit。
buscoquadnary查看英文原文
I thought literate program was a farsical esoterica that was only born because of it's ivory tower surroundings, and would've stillborn had it come into the world any other way. Until I found org-mode it really is world changing if I had picked up Doom Emacs for no other reason than org mode it would've been well worth it. I have now seriously considered trying to do literate program with org mode. It's already seeped into every project I work on now has a notes.org where I keep kind of a stream of consciousness notes of what I am doing and copy and paste any code or command I have into it for future reference and it has already multipled my productivity. I love org mode and for any person that is already a vimmer I recommend highly you pick up Doom Emacs and spend some time getting to become familiar with it, especially org mode and magit it really is world changing. I can't imagine ever going back.
文档与代码失同步是真实痛点，把文档接入自动化测试是可落地的解法。
上一份工作我写过类似的东西，主要因为前端开发想要好文档，而文档总跟代码库脱节。于是我把文档接进测试框架（附了项目链接）。
moeris查看英文原文
I wrote something similar at my last job. Mostly because the frontend devs wanted good documentation, and the docs kept falling out of sync with the codebase. So I integrated it with a test framework: https://github.com/savantgroup/literate_integration
文学编程的门槛是写作、编程、自动化三重技能叠加，回报是长期的代码可读性。
我热爱文学编程，但它要求三种技能叠加：写得好、编得好，还得懂一点 DevOps 才能自动执行文学程序。所以其实非常难做……但结果值得，你能得到一份永远看得懂的软件。
elviejo查看英文原文
I love literate programming. But it requires 3 skillets: writing well, programming well and a little DevOps in order to automate the execution of the literate program. So it is actually very difficult to do... But the results are Worth it to have software you can understand forever
术语要慎用：文学编程有特定含义，别把它泛化成「代码里加注释」。
我不会把这个算作文学编程的例子，至少不是 Knuth 那种意义上的文学编程。
nesarkvechnep查看英文原文
I wouldn't call this an example of literate programming. At least not Knuth's LP.
同类还值得读
编写更好文档的框架
A Framework for Writing Better Documentation
这是 Divio 的文档写作框架，把技术文档按「读者的目标」分成四类：教程（学习导向）、操作指南（问题导向）、参考（信息导向）、解释（理解导向）。
技术写作与文档2021 · 637 分 · 76 评4 条写作要点编辑精选写好一份设计文档
Writing a good design document
这篇 HN 帖子标题为《Writing a good design document》，主题是如何写好一份设计文档；对写作者来说，它值得作为技术写作和结构化说明文的参照。
技术写作与文档2025 · 581 分 · 147 评3 条写作要点编辑精选技术写作课程
Technical Writing Courses
这是 Google 官方免费技术写作课程（两门），讲受众定义、主动语态、短句、文档结构等基础方法。
技术写作与文档2020 · 571 分 · 73 评4 条写作要点编辑精选写出更好的错误信息
Write better error messages
这篇帖子讨论如何写出更好的错误信息，评论补充了开发者场景下的具体做法和真实反面案例。
技术写作与文档2022 · 566 分 · 253 评4 条写作要点编辑精选写一本技术书的经济账
The Economics of Writing a Technical Book
一位技术书作者拆解写书的真实经济账：版税收入往往远低于投入的时间成本。
技术写作与文档2018 · 519 分 · 149 评4 条写作要点编辑精选