围绕社区对女性、新手或非“圈内人”不友好的新闻周期并不少见。我说的“新闻”是指有人发布了一些贴近他们内心，关于某些不公正的事情，其他人对此评论或撰写自己的帖子，总的来说，故事的寓意是：但我们应该做得更好！
作为整体社区的一部分，这是正常且期望的行为。这个周期是好事，因为它促使人们思考他们作为社区成员的行为，以及作为局外人的感受，以及他们如何改进。这些都是积极的步骤，因为它源于想要成为更好的人的真诚愿望。这太棒了。
最近，我一直在涉足我不太常接触的技术领域。其中一个领域是通过查看文档来学习一项新技术。这段特殊的旅程始于成为 Google Glass 探索者，这是一个我在自己的博客 amye.org 上谈论过的故事，所以这里我就不赘述了。但是，一天深夜，当我浏览关于 Android 实际功能以及你的智能手机硬件具有的所有（坦率地说令人惊叹的）功能（环境气压，有人用过吗？）的文档时，我突然意识到文档是我们这个时代伟大的均衡器之一。
每个人都必须阅读文档。 每个人。 你知道那些时候，你直接上手，懒得看手册，然后想知道为什么它不起作用？ 嗯，是的……这发生在每个人身上。“只是下载下来试试看”的人和编写了大量代码的人都对文档有着既得利益。诚然，他们的兴趣范围不同，但两者都是有效的。我把它想象成一个刚开始学习识谱的三年级学生和一个可以瞬间视奏的专业钢琴家——但是，他们都需要乐谱才能知道接下来要弹奏的音符是什么。
鉴于这种背景，你的开源社区中的文档说明了你对社区的期望。我知道我会收到很多关于你的代码是自文档化的评论。不，先生们和女士们，它绝不是。期望你的代码是自文档化的，就像在森林中标记个别树木，而不注意森林位于何处一样。这是在北极吗？热带地区？当我拉起那块石头时，我可能会在下面发现什么样的生物？我正在看什么，以及我期望接下来去哪里？
我很享受阅读 Android 文档的过程，因为它是一个平台，并且几乎在每个转折点都会告诉你。它定义清晰，布局合理，但仍然有一些词汇是不熟悉的。
前段时间，我偶然看到了 @relsqui 的这条推文，它一直让我记忆犹新……
理论：缺乏文档会助长冒名顶替综合征。“我一定应该已经知道这个了/应该能够自己弄清楚……”
这就是我一直记住它的原因——它可能只是一个理论，但理论是最高的科学规律，而证伪它取决于我们。有很多事情你可以做；仅仅在你完成一个项目时保持一个运行的文本文档也是很有帮助的。
底线：如果你不打算为你以外的人记录你所做的事情，那么为你未来的自己做这件事怎么样？你的未来自己会在六周后回来，却不记得你要去哪里了？
2 条评论