我如何说服我的团队编写更多文档

文档是每个开发人员在谈话中都会称赞的事情之一，但可能做得不够，甚至根本不会。我们都听过无数个文档好的理由。它有助于知识传递，让每个人都能达成共识。它能让新人避免完全迷失方向，无需缠着其他开发人员，通过清晰的对话来灌输知识。它还能让你未来的自己避免咒骂过去的自己。文档是让团队保持活力和运转的神圣文本。

尽管我们都认同文档的好处，但很少有团队真正投入时间去认真编写文档。文档被搁置一旁。有太多实际代码要写，有太多紧急事件要处理，有太多截止日期要错过。那么，如何让你的团队投入精力编写更多文档呢？你得蒙骗他们。

我的团队

我是动视暴雪的《使命召唤》配套应用的开发者。我们团队规模虽小，但凝聚力很强。我相信我已经找到了一种让团队编写大量文档的方法。我相信这些经验和技巧可以适用于任何团队。几个月前，我们几乎没有花时间去记录。现在，我们花了很多时间去记录。

但在我解释我们是如何走到这一步之前，有一件事是最重要的：不要对别人颐指气使。我从来都不相信对同事指手画脚。真正的改变发生在更真实、更自然的层面。所以，重要的是要明白，“你应该多写些文档”这样的话绝对行不通。行为不会一下子改变。你的同事们已经排满了感恩节期间堆积如山的其他任务和责任，所以我们需要一个比提出要求更好的解决方案。

第一阶段：行动

那么，我究竟是如何让团队加入文档编写的潮流，并推出大量真正有用的文档的呢？很简单。我开始写文档。

你必须成为第一个挺身而出编写优秀文档的人。一旦你做到了，你就拥有了一个编写文档的团队。即使目前只有一个人。你也应该在工作过程中编写文档。每当你修复某个问题、设置新流程、构建新功能，或者任何其他值得记录的事情时，它都应该成为你日常工作的一部分。

好的，但现在你在想“如何让团队的其他成员编写文档？这不就是我们讨论的重点吗？” 接下来你需要采取以下步骤，让其他人也参与进来。

第二阶段：宣扬你正在做这件事

恭喜！现在你真的开始写文档了。而且每次觉得有必要的时候你都会这么做。这是吸引其他人也这么做的关键基础。现在你需要开始宣传你正在写文档。

每当你撰写新的 wiki 文章或文档时，你都需要委婉地告知所有人。请注意“委婉”这个词。记住，优秀文档的目标是增强团队凝聚力并提升产出。所以你的措辞应该体现这一点。“我刚刚为我刚刚构建的功能 X 编写了这个 wiki 页面。它告诉了你开始使用它所需的一切信息。如果你认为我遗漏了任何内容，请告诉我。”

现在，你已经向外界表明你正在编写文档，并向你的同事们传递了同样的信息。他们会看到编写文档的价值，因为他们会打开你关于功能 X 的维基页面，并快速了解功能 X 的作用。你赋予了他们自主权。如果团队中有四个人，那么你也赋予了他们所有四个人自主权。

第三阶段：让其他人知道什么时候做这件事是有用的

既然你已经开始公开自己会写文档了，那就可以找机会建议他们也写文档了。是不是其他团队成员刚刚完成了功能 Y 的构建？或者他们是不是想出了一个新方案来构建 Xcode 项目，避免了那个奇怪的 bug？他们有没有做过什么让你觉得“哇，我完全不知道怎么做，如果我和团队都知道怎么做就好了”的事情？这些时候你就可以委婉地建议他们写一些文档。“嘿，那个新功能超级好用！你愿意花点时间写点东西介绍一下吗？”

很可能你最初几次建议记录的时候，他们不会去做。这很正常，没关系。没必要纠缠不休。事实上，纠缠不休或反复强调你想要记录某件事，只会让他们觉得你还在往他们已经满满的盘子里添东西。但要保持一致。每当出现值得记录的事情时，就继续使用同样的策略，让他们知道如果他们记录下来会有多大帮助。如果他们确实记录了某件事，一定要表达感谢。

第四阶段：提醒别人你做到了

我认为最有力的说服力就在于此。这实际上会让你的团队成员也参与编写文档。确保尽可能多地参考你的文档。如果有人问你：“我该如何再次完成 X？”，那么你应该能够引导他们查看相关的文档。如果你坚持在工作中编写文档，那么这些机会就一定会出现。不过，不要太过分。首先，你应该像文档不存在一样认真地回答他们的问题。仅仅提供文档链接可能会显得粗鲁或消极被动。帮助你的同事，然后礼貌地提及一些类似“嘿，顺便问一下，这是我们文档中的信息，以防你以后需要它。”

结果

所以，也许所有这些不一定都是诡计，但说起来比“树立一个好的榜样，礼貌地展示优秀文档的价值”更有趣。如果你坚持这四个策略（持续编写文档、编写文档时进行宣传、建议其他人何时可以编写文档以及尽可能参考现有文档），我相信你最终会获得关注，团队的其他成员也会开始编写更多文档。它一开始会像涓涓细流，然后像多米诺骨牌一样，最终变成雪崩。

在《使命召唤》配套应用团队，我一开始只是记录一些简单的东西，比如我们的风格指南或推送通知功能的信息。我坚持自己的方法，后来有一天，我的团队负责人制作了一个动图，演示如何在 Xcode 中配置设置，并附上内部 wiki 文章中的一些说明。就这样，涓涓细流开始了。之后，另一位开发人员开始记录组件，并附上截图和组件使用方法的详细说明。现在，我们都在定期撰写文档。我们的文档帮助我们所有人保持一致。我们看到它加快了我们的开发进程。现在，每当我们出现“404”错误，忘记了如何操作某件事时，我们不用再手忙脚乱地摸索，浪费时间重新摸索。我们的文档里有所有内容。

如果您希望获得类似的结果，您需要做的就是欺骗几个人。