编程大牛的回答
GitHub 刚刚发布了《2017 开源调查》报告,这家知名编程社交网站走访了 github.com 社区内 3800 多个项目和超过 5500 名成员,并且与 500 名在 GitHub 项目生态系统之外的编程者们进行了交谈。本次调查涉及多方面,比如人们在为开源项目做开发、做贡献时遇到的问题,结果有 93% 的人对“不完整或令人困惑的文档”感到非常沮丧。
英语世界里,文档非常受重视,许多公司和组织都有自己的文档规范,清楚地规定写作要求,比如微软、MailChimp、Apple、Yahoo、docker、Struts 等等(维基百科有一份完整的清单)。中文的也有不少,但都不令人满意,要么太简单,要么不太适用。我就动手,参考上面的规范,也结合自己的实践,总结了一份简单的《中文技术文档的写作规范》。
好的代码,就像是好的笑话——无需解释就能让别人明白。如果你的代码能够做到不解自明,在大多数时候,你根本无需为其配备说明文档。
【外评】法官驳回大部分 GitHub Copilot 版权索赔要求
谷歌内部推出 SQL 中的管道(Pipe)语法
你们干扰不了我写开源代码
【外评】FreeBSD 将 Rust 纳入基本系统
【外评】电脑从哪里获取时间?
【外评】为什么 Stack Overflow 正在消失?
有时
【外评】哪些开源项目被广泛使用,但仅由少数人维护?
【外评】好的重构与不好的重构
【外评】代码审查反模式