技术写作与文档2013github.com
把代码文档当作代码来写
Code documentation written as code
导读
这篇 HN 帖子链接到 Learn X in Y Minutes 仓库，该项目用带注释的代码示例来讲解编程语言。讨论集中在两点：这种“代码即文档”的格式为何适合技术说明，以及发帖时只贴链接、缺少上下文会带来什么问题。对写作者来说，它提供了一个可迁移的写法：用可运行、可对照的示例承载解释，而不是先堆抽象定义。
可以直接用的写作要点
- 01
用“可运行示例+逐行注释”代替抽象定义，让读者边看边理解。
- 02
发布或分享内容时先补一句“这是什么、为什么值得看”，不要只甩一个链接或仓库。
- 03
同一套示例体例可以复用到脚本、命令行工具等不同主题，用一致结构降低理解成本。
- 04
介绍一种方法时简要交代已有传统或先例，既显专业，也避免把旧想法包装成新发明。
HN 评论精选
只给链接不给说明，读者会困惑，传播效果也差。
我到底在看什么？我觉得如果你想让你的 HN 帖子获得关注，就应该比单纯贴一个 git 仓库链接多花点心思。
Nilzor查看英文原文
Exactly what am I looking at here? I think if you want attention to your HN-posts you should put a bit more effort into it than simply linking to a git repo.
代码示例加注释的格式可迁移到各类技术文档。
这是一种很棒的格式，适用于很多中低层计算机任务。编程/脚本当然可以，现在还有工具部分，我猜也会流行起来。你可以用这种方式描述 ip(6)tables 或 ssh。
spindritf查看英文原文
This is a really great format which lends itself to a whole range of mid-to-low level computer tasks. Programming/scripting, obviously, but now there's a tools section which I'm guessing will also catch on. You could describe ip(6)tables like that, or ssh.
用代码/示例讲解并非新创意，写作时可交代渊源，避免显得重复造轮子。
OP 在说什么？像 Dijkstra 这样的人从 1970 年代起就在倡导这种做法了。
gcr查看英文原文
What is OP talking about? People like Djikstra have been advocating this since the 1970s.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选