技术写作与文档2015archieml.org
ArchieML：为人类可写性优化的结构化文本格式
ArchieML is a structured text format optimized for human writeability
导读
这篇介绍 ArchieML——一种为「人写得顺手」而优化的结构化文本格式，常用于编辑室里把文档中的结构化数据抽出来。讨论既有对「简单即好」的赞赏（拿 INI 作比），也有对其「不报解析错误」策略的批评，还追问了它与 TOML 等现成格式的关系。对写作者来说，它提醒我们：格式本质上是人和机器之间的沟通契约，设计格式时要同时考虑写得顺手和错得可查。
可以直接用的写作要点
- 01
设计或选用格式时，优先考虑人手写的顺手程度，而不只是机器解析的便利。
- 02
简单往往最好：INI 式格式说明，规则越少、越直白，越不容易写错。
- 03
别把「不报错」当成「没错误」——结构写歪了却看起来像普通文本，问题只会在后面爆发，写作时要主动校验结构。
- 04
引入新格式前先讲清它相对 JSON/YAML/TOML 解决了什么，否则读者第一反应就是「为什么不用现成的」。
HN 评论精选
批评「不报解析错误」的设计，认为隐藏错误只会在后期造成更大问题。
「无结构的文本会被忽略；不存在解析错误这回事」——这是个天真且方向错误的做法，问题会在后面冒出来。如果结构被打错，以至于看起来像无结构文本呢？这个格式是有结构的，因此该格式的示例也可能出错。你不诊断错误，不代表错误不存在。
kazinator查看英文原文
> "Unstructured text is ignored; there is no such thing as a parsing error" That is a naively wrong-headed recipe for problems later down the road. What if structure is mistyped such that it looks like unstructured text? The format has structure, and consequently, examples of that format can be erroneous. Just because you don't diagnose errors doesn't mean they aren't there.
简单格式（如 INI）往往最实用。
让我有点想起 INI 文件。它们很好地证明了有时简单就是最好的。
TazeTSchnitzel查看英文原文
Reminds me a little of INI files. They are a good demonstration of how sometimes simplicity is best.
质疑为何不与 TOML 比较，新格式应说明相对现有方案的优势。
有意思的是，文中提到了 JSON 和 YAML，却没提 TOML。我更想听的是：为什么 TOML 不算一个够用的方案。
burke查看英文原文
Interesting that there's mention of JSON and YAML, but no mention of TOML. I'm more interested in hearing why TOML wasn't an adequate solution.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选