程序员为什么一定要会写文档？

我是 Postman 开放技术计划办公室的负责人，最近，在一次 Postman Open Technologies 团队会议上，我提出了一个非常笼统的方向：我们必须成为以文档著称的团队，并需要个人和团队共同记录所有内容。 虽然还有更多背景信息，比如我们与产品团队的协作等等，但这也是我给自己以及其他从事工程、OSPO 或开发者关系领域工作人员提供的通用建议。

首先让我们定义“文档”这个词。在本篇博客文章中， “文档”包括外部和内部技术文档、博客、社交网络分享知识、演示、操作指南、会议报告、网络研讨会、播客节目、维基 百科 页面、信息图表等等。

我理解在当今快节奏的世界中容易迷失于各种职责。但是，虽然编写文档不像编写代码、设置流程或解决问题那样能立即获得回报，但创建良好的文档是向周围人以及未来自己展现同情心的表现。它的影响是中长期的，但需要现在优先考虑。 我认为，文档高手最终会成为人生赢家。以下是 10 大理由。

• 理由一：记录让你成为更好的同事和协作者

创建良好的文档可以减少挫败感，降低协作带来的焦虑水平，并使以前的决策更易理解。

• 理由二：记录增加了你的价值

它提高了你作为专业人士的价值，并使你不那么容易被取代。放弃一个内部知识管理做的很好的人或团队，是痛苦的。雇用一个以构建持久知识而闻名的人，是明智的决定。

• 理由三：记录有助于建立个人品牌

在进行研究时反复遇到相同作者名称，会使你成为主题专家。再加上其他措施，如社区参与、指导、公开演讲等——将极大地帮助你打造自己品牌。

• 理由四：记录增加了内部可见性

能够引用自己编写的东西，比模糊地重复在团队会议上说过什么要容易得多。如果很容易做到这一点，同事们更有可能给予赞誉。

• 理由五：你可以把它切割成内容创作块

一旦开始记录东西，就可以将其切割并制作内容创作块 。制作视频、撰写播客叙述、准备演讲或邀请具有相似或不同观点的人参加小组讨论比从头开始要容易得多。它还可以帮助你找到故事线索。

• 理由六：记录有助于内化你的知识，并识别注意事项

重复，这就是人脑的工作方式。写下来正好符合此情况。当你打字速度比大脑处理信息快时，你强迫自己反复重复同样的事情，有助于你内化发现结果，或帮助你在思考中找到陷阱和错误。

• 理由七：记录使你的知识持久存在

你是否曾经遇到过一个书面材料，并想，“嘿，真是很好的知识，我很高兴别人把它写下来了！”但忽然发现，这些文档就是你自己两年前写的！我们会忘记，甚至这也是我们学习过程中所包含部分内容之一 。存储信息不仅仅是为他人而做某些事情 ，同时也为自己做某些事情 。即使你不定期更新内容 ，它在一段时间内甚至可能超出预期。

• 理由八：记录节省时间

你可能认为恰恰相反，编写文档会占用大量时间？你有没有觉得自己在重复自己？这可能是因为你确实如此做了 。当你编写文档时，它可以避免让你反复解释同一件事情的繁琐工作。

• 理由九：助于避免尴尬的询问

如果一周内，你连续三四次解释同一个老问题，你会感到无聊，你的同事也会尴尬，他们也会因浪费你的时间而感到难过，也可能会因觉得你太忙碌而退缩，这会妨碍协作。

• 理由十：记录让你更擅长讲述

整体情况是你将被要求提供的内容，不仅能够提供事实和数字，还能够很好地讲述并使数字深入人心，这是最为珍贵的。

需要注意的是，虽然我说“好文档”，但我并没有要求“优秀”或“出色”。不是因为我认为永远不会有完美的东西，而是因为文档没必要完美无缺。通常，“普通文档”就足以胜任工作，并且在努力和效益之间达成了合理的妥协。

每当需要文档时，你都要坚定地说：来吧，写吧！

Eolink 翻译,原文《10 reasons why you have to exceed at documenting》，作者：Jan Schenk

【编译后记】

编译完成后，我发现作者这篇文章可以组织得更好，比如从个人、组织、同事协作三个角度对10个理由进行分类，会更好。否则10个理由是有认知负担的，记住3个方面的理由总要比记住10个容易得多。

一百年前，鲁迅曾批评文化“十景病”、“八景病”，总要凑到十个或者八个，现在看外国人也不能免俗。如果用在风景名胜，十个八个听起来响亮，但技术文章未必要这么做，清晰的分类更重要，太多反倒是认知负担。