在我们脑海中的某个地方，从事软件项目的每个人都知道文档是一件非常好的事情。 尽管有这种意识，但文档的优先级通常低于其应有的优先级。
许多可以理解的动机导致文档的优先级较低。 为了正确确定文档的优先级，我们需要检查组织面临的Document-Discouragers©。
Documentation-Discourager 1：没人要阅读它
一定比例的文档可能永远不会被阅读，但是文档的好处胜过偶尔未读页面的弊端。 也就是说，除非团队养成习惯使用文档，否则文档无用。
每当您被问到问题时，这都是一个鼓励阅读文档的习惯的机会。 如果有可能，请不要回答。 相反，请提供指向文档的链接。 如果不存在任何文档，其他人可能会再次问到这个问题，请先创建文档，然后使用链接进行答复。 除了节省将来的击键操作之外，这还创建了一个集中的信息源。 它消除了发生某些更改时获取过时信息的风险，并且获取此信息不再取决于某人答复电子邮件。
Documentation-Discourager 2：我写的东西实际上有用吗？
文档化的最大好处之一就是可以从根本上防止问题的发生。 经历一个问题要比没有发生要突出得多，因此很容易忘记文档的实用性。
每当组织中的某人将问题归因于沟通问题时，他们都会间接地说“这可以通过良好的文档/阅读文档的意愿来避免”。 使用文档，信息是一致的，随时可用，并且可以在发生更改时立即更新。
在某些情况下，我发现文档最有用：
- 交叉培训/入门更加容易：最近，我们的团队暂时没有QA测试人员。 我不必负担已经很忙的质量检查部门的工作，而是可以使用文档来告诉自己如何使用我们的质量检查工具。 新员工也将从此类文档中受益，填补了面对面培训中不可避免的空白。 他们也不会被迫仅依靠内存来保留入职流程中显示的大量信息。
- 变更的破坏性较小 ：在组织中， 变更总是在不断变化，但是向所有人宣布每项变更都会适得其反，而且不清楚谁需要知道新IP，登录URL和更改的密码等事情。 文档可以防止某些行为与预期不同时经常发生的恐慌。
- 更少的会议：不止一次，我被邀请参加一个会议，讨论一个我已经详尽记录的话题。 我拒绝参加会议，使用文档的链接进行回复，如果文档未提供必要的信息，则建议重新安排。 到目前为止，这消除了每次会议的需要。
- 更改和改进要容易得多：通常，在我们逐步淘汰系统时，有关系统的文档非常重要。 如果我们要替换群聊或CRM等工具，则在替换它之前了解该工具具有何种依赖性以及使用该工具非常重要。 在迁移之前确定这些依赖关系非常耗时，并且存在忽略关键问题的高风险。
- “我不知道该问谁”不是问题：在Wiki上查找信息可以使我们摆脱试图找出组织中谁可以回答问题的笨拙。
文档化-Discourager 3：收益难以轻松量化
如上所示，文档提供了许多好处。 它们很难衡量，因为这些好处通常是预防性的，而不是增加的价值。 可以通过回顾过去可以通过文档解决的问题来进行一些量化，但是这种度量取决于发生的问题。 将文档视为促进后续可衡量成就的营养可能更为有用。
上面“实际上有用”部分中的所有好处都是最终节省时间和金钱的好处。 除其他事项外，文档可以使员工的上岗速度更快/更彻底，花在回答问题和寻找答案上的时间更少，花在收集相同信息上的多余工作时间也更少。 消息灵通的员工将获得更大的回报。
Documentation-Discourager 4：我的经理对新功能更加兴奋
新功能比文档更令人兴奋。 如果软件开发是一顿大餐，那么文档将是菜（不做任何准备）。 管理人员需要向内看，并记住该文档在几个月后将变得多么有价值。 意识到文档可以防止的未来问题应该足以激发一些鼓舞士气的热情。
Documentation-Discourager 5：我找不到时间去做-每个人都在要求软件，而不是文档！
文档时间需要像其他任务一样安排。 可以将文档时间作为生产计划的一部分，但是将其分配给“以后会解决”仍然很容易。
我们的团队在弹性工作日编写文档方面取得了成功。 我们很幸运，每周有一天不要求我们处理当前的项目。 这次，最有效的用法之一是*实际上*正在研究将要解决的问题，而这些问题通常是文档编写的。
Documentation-Discourager 6：编码比编写文档更有趣
老实说，这是真的，不能揭穿它。 建立某种东西所产生的内啡肽远比撰写它多得多。
我唯一能说的是，文档将大大减少以后需要开会的会议和问题的数量，从而腾出时间进行更多的编码。
结论
我认为我现在对文档的立场很明确。 尽管它一点也不浮华，也不是一个理想的度过下午的方式，但好处却是巨大的。 在ITHAKA，我们的文档以Atlassian的Confluence作为Wiki提供。
ITHAKA是我与内部Wiki合作的第一个组织，该内部Wiki涵盖了除基本HR信息之外的所有内容。 我仍然想起以前的工作，如果我们使用内部Wiki，本来可以轻松解决多少个问题。 此外，在重视和腾出时间来完成文档等任务的团队和组织中，精神焕发。 当您可以将组织引至文字页面时，使组织位于同一页面上会大大简化。
