技术写作与文档2012stdout.heyzap.com
如何写出能自我说明的 API 文档：Heyzap API 发布
How to Write a Self-Documenting API - Heyzap API release
导读
这是 Heyzap 团队分享如何让 API 文档“自我说明”的实践文章：把说明放进 API 根路径的响应里，让调用者不必翻外部文档就能看懂接口。对写作者来说，它示范了一种“让文本自己解释自己”的思路——用示例、入口说明和分层呈现替代冗长说明，值得借鉴到技术写作与说明性写作中。
可以直接用的写作要点
- 01
把最有用的说明放在读者第一眼看到的位置（如 API 根路径），而不是藏在附页或附录里。
- 02
用真实示例响应代替抽象描述，读者照着例子就能上手，减少解释成本。
- 03
同一份内容按读者类型分层呈现：人看到可读的页面，机器看到结构化数据。
- 04
让文档可被发现、可被追踪：通过链接和跳转把零散说明串成一张可探索的网。
HN 评论精选
文档应默认对人友好，别把可读性推给读者的工具。
我很喜欢“在 API 根地址放点有意义的内容”这个技巧，以后会用上。文中说“你当然需要一个 JSON 查看器插件才能看”，那为什么不干脆在服务端就把 JSON 输出得漂亮一点呢？
hinathan查看英文原文
I like the trick of placing something meaningful at the api root url, will use that in the future. "You of course need a JSON viewer plugin to do this." Why not emit your JSON slightly prettier from the server side? http://stackoverflow.com/questions/86653/how-can-i-pretty-format-my-json-output-in-ruby-on-rails
同一地址按请求类型返回人读页面或机器读数据，是自我说明的好办法。
可能有人没见过：django-rest-framework 内置支持可浏览、自说明、带 HATEOAS 的 API。浏览器默认发送 Accept: text/html，所以在 API 根路径会返回一个描述结果的漂亮 HTML 页面；点底部的“json”发送 text/json，就得到 JSON 响应。你还能顺着 HTML 里的链接走到 API 的其他部分，点“OPTIONS”则发送 OPTION 请求，得到该端点可提交内容的说明。
slewis查看英文原文
For those who haven't seen it, the awesome django-rest-framework has built in support for browsable, self-documenting, HATEOS APIs. Here's a browsable example API: http://rest.ep.io/ Because your browser provides Accept: text/html by default you get back a nice html page describing the result for the API root. If you send Accept: text/json (click "json" at the bottom) you get back a json response. You can follow the links in the html response to get to other parts of the API. You can also click "OPTIONS" to send an OPTION request to get a description of what you can send to that endpoint. http://django-rest-framework.org/
自我说明不应局限于 Web 接口，任何衔接处都适用，且要对机器可发现。
他们似乎专门在谈 RESTful 及相关 API，但在我看来，自我说明的 API 应该存在于应用的各个层次。我更进一步认为，真正自我说明的 API 应当既能被人发现，也能被软件发现。我们在 LedgerSMB 就为此下了很大功夫，连存储过程都这样做。凡是软件之间发生连接的地方，这都可能是好做法，何必局限于 Web？
einhverfr查看英文原文
They are talking specifically, it seems, about RESTful and related API's, but self-documenting API's IMO should be present at other levels of an application too. I would take it further and say that truly self-documenting API's should be discoverable by software as well as individuals. This is something we have worked on hard at LedgerSMB, doing so with stored procedures even (see http://ledgersmbdev.blogspot.com/2011/10/introduction-to-soda.html for more info). Anywhere there is a connection between software, this can be a good approach. Why limit it to the web?
版本号塞进 URL 未必是最佳做法，值得参考其他版本化思路。
看到 /v1 前缀，我想起 Steve Klabnik 的一篇博客，他在那里给出了一种替代做法，可以说更符合 REST 的 API 版本化方式。
waffle_ss查看英文原文
When I saw the /v1 prefix I was reminded of one of Steve Klabnik's blog posts[1], where he gives an alternative, arguably more RESTful approach to versioning an API. [1]: http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http#i_want_my_api_to_be_versioned
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选