标签归档:文档

码农不重视文档:开源项目深受其苦

GitHub 刚刚发布了《2017 开源调查》报告,这家知名编程社交网站走访了 github.com 社区内 3800 多个项目和超过 5500 名成员,并且与 500 名在 GitHub 项目生态系统之外的编程者们进行了交谈。本次调查涉及多方面,比如人们在为开源项目做开发、做贡献时遇到的问题,结果有 93% 的人对“不完整或令人困惑的文档”感到非常沮丧。

阮一峰:中文技术文档的写作规范

英语世界里,文档非常受重视,许多公司和组织都有自己的文档规范,清楚地规定写作要求,比如微软、MailChimp、Apple、Yahoo、docker、Struts 等等(维基百科有一份完整的清单)。中文的也有不少,但都不令人满意,要么太简单,要么不太适用。我就动手,参考上面的规范,也结合自己的实践,总结了一份简单的《中文技术文档的写作规范》。

这样的代码才是好代码

好的代码,就像是好的笑话——无需解释就能让别人明白。如果你的代码能够做到不解自明,在大多数时候,你根本无需为其配备说明文档。