不要害怕Docs！

夜色越来越深，影子越来越长。枯叶的沙沙声取代了蟋蟀的鸣叫声。这是恐怖的季节，最可怕的威胁就是未知！

这就是为什么现在该谈谈文档了。糟糕的文档不仅会降低工作效率，还会使您更容易受到网络攻击，并在关键时刻拖慢您的速度。文档记录不善的 API 是许多恐怖故事的根源——您可能也会讲出一些自己的故事！

您可能没有意识到，您可以从恐怖电影的生存“规则”中学到很多关于如何穿越令人毛骨悚然的文档迷宫的知识！

获取蓝图

您是否曾尝试在不知道楼层平面图的情况下逃离闹鬼的酒店？或者在没有入口地图的情况下在废弃的商场中躲避僵尸？当您的 API 文档不完整时，如何实现安全的数据隔离？

另一种表述方式是：最大的风险是未知的未知数。

您可能认为自己已经检查了清单上的所有项目，但如果清单本身不完整，您几乎肯定会忽略重要的风险。当您在 API 开发过程中包含文档时，您将获得一个内置的审计工具，可帮助您绘制风险并创建更强大的 API 产品和集成。

外部风险形势总是在变化。随着新威胁的出现，了解您的风险暴露至关重要。您不想重新了解您的形势或花费宝贵的时间来找出您的弱点。

好的文档就像一张地图，但创建地图的过程有其自身的好处。当您的团队创建“地图”时，他们应该注意一些关键的安全因素：

• 您是否拥有一致、严格的数据隔离？敏感数据位于何处？绝对不能暴露在哪里？
• 您首选的身份验证做法是什么？您是否在所有资源中始终遵循这些做法？
• 您是否有清晰的方法来跟踪依赖项？您是否使用自动修补和更新？如果没有，您如何确保您的依赖项保持最新状态？

在制定安全事件响应计划时，您应该能够列出您的风险暴露的明确清单。创建文档的过程将帮助您实现这一目标。到时候，这些文档将让您有信心快速做出响应。

确保僵尸确实死了

如果你看过僵尸电影，你就会知道真正的危险发生在你以为僵尸已经死了之后。在你以为已经消除威胁之后，威胁还会不断变化和增长。它们总会回来的！

僵尸 API也是如此，那些旧版本和废弃项目仍然存在。非托管 API 占所有 API 的 50% 以上。您可能很久以前就引导用户远离弃用版本，或者在项目投入生产之前就放弃了它，但任何面向公共网络的端点仍然存在风险，特别是如果您没有关注谁在访问它们。过时的 SDK 也是未维护资源的常见流量来源——您需要全面考虑 API 的流量可能来自何处。

我们再说一遍——最大的风险来自未知。如果您没有积极维护在线服务（无论是 API 还是其他服务），您就会面临不必要的未知风险。理想情况下，您应该只维护必要的 API，并在六个月内逐步淘汰任何“僵尸”API。

那么，良好的文档如何帮助您确保已经消除了僵尸 API 并控制了风险？

首先，必须有一个单一事实来源，列出您维护的所有公共端点。自动列出端点列表是一个开始，并且有审计工具可以帮助您做到这一点。您可以定期重新运行审计，以确保已停用的服务已被删除。

一旦你有了所有 API 和端点的明确列表，你就会希望将该列表与我们上面讨论的信息集成在一起。你如何了解依赖关系或敏感数据暴露？谁将负责监控这些信息并将其转化为有用的文档？

完善的文档实践还可以帮助您监控 API 程序的范围，清晰了解停用 API 的后果，并向利益相关者和消费者透明地传达变更。组织中的不同工作职能需要彼此以及来自外部 API 消费者的不同详细信息和背景，但确保它们都来自同一个事实来源至关重要。 

保养汽车并打包用品

你惊慌失措，没有时间逃跑，但你有车！这是一部恐怖电影，所以你可以猜到会发生什么——车子发动不起来。或者你忘了带钥匙，你没油了，你忘了重要的东西，不得不掉头……

没有人会计划不做好准备。然而，做好准备是一个积极、有意识的过程。问自己两个问题来评估你的准备工作：

• 我们如何系统地跟踪我们的依赖项和第三方工具？
• 我们如何持续地将个人知识转化为机构知识？

API 蔓延使您需要时更容易出现问题。在主动网络攻击期间，您不宜发现自己在不同资源上使用不同的身份验证模式。生产中断时，您不会发现自己正在使用未维护的依赖项，或者不知道哪个客户正在使用哪个版本的 API。您需要清楚地了解您的依赖项、功能和限制，以便在危机发生之前解决问题，并在危机发生时果断采取行动。您有什么工具或实践来审核您的文档？您是否确信您拥有服务架构和产品功能的完整记录？

组织扩张可能产生与 API 扩张类似的后果。当一两个人掌握关键知识时，您不能指望他们在危机中能够访问这些信息——这在快速发展或工作职能高度孤立的组织中是一个特别常见的问题。您有多大信心将关键知识记录下来并编入索引，以便在危机中快速找到它们？将文档集成到您的开发和 QA 流程中有助于确保信息在需要时和需要的地方可用。

永远团结在一起

恐怖电影的首要规则是：永远不要单打独斗。你知道这也是 API 文档的规则吗？并非每家公司都能负担得起专门的技术作家，但即使是专业程度较低的团队也能提供比任何个人努力更有价值的文档。

文档编写是一门学科，拥有经过充分研究的实践和专业工具。理想情况下，您会找到一位经验丰富的技术作家来领导您的文档编写工作。即使您做不到，您也希望组建一支具有以下优势的团队：

• 技术知识：文档编制过程应该是对设计和实施的“健全性检查”。开发团队的技术同行的审核将为您带来最大的价值。
• 客户视角：开发倡导者、产品经理和支持工程师都会对 API 消费者需要了解的内容有重要的见解。
• 写作技巧：文档需要简洁准确。如果能引人入胜就更好了。好的写作需要练习，所以您需要团队成员长期优先掌握这些技能。
• 信息架构：创建信息只是成功的一半。组织信息以使其有用同样重要，而且并不总是直观的。根据文档的范围，您可能需要的不仅仅是开箱即用的文档工具。

小心不要过度依赖一个人来处理文档，也不要让工程师负责自己的文档。如果你想要有用的文档，你需要让团队共同努力，如果你想让它可持续，你需要分担工作量。如果你能让文档成为常态并分担工作，你就会减轻个人的负担并增加认同感。没有人愿意独自一人走进黑暗，当你和其他人一起工作时，你会更强大、更安全。

保持警惕

我们需要补充两条生存法则：永远不要背对威胁，永远不要说“我马上回来！”换句话说，保持警惕至关重要。你需要通过几种方式来保持警惕。

自动化文档是工具包中一个很棒的补充，但您知道不能让机器人无人看管，对吧？我们非常肯定您的人身安全不会受到自动化文档的威胁，但您仍然需要人工监督。如果您需要工程师对彼此的工作进行同行评审，那么您当然需要对自动化工具产生的工作进行同等程度的审查。这些​​工具并不完美，因此您需要监控错误。您还可能会发现这些工具会发现人工审查忽略的不一致之处，而这些不一致之处在文档中比在代码中更明显。

我们知道您有很多事情要做，而且很容易认为文档可以等。然而，废弃的文档项目墓地和任何恐怖电影墓地一样满。文档需要及时创建，否则很可能无法完成，因为总会有更紧急的事情。这就是为什么构建使文档变得简单的流程和框架是值得的。一旦建立起来，跟上变化就会容易得多。只是不要让它从视野中溜走，否则僵尸 API 的可怕威胁可能会在您最意想不到的时候悄悄出现！

您永远不想对威胁置之不理。安全形势总是在变化，您不能坐视不管。没有理由惊慌，尽管我们无法预测明天会发生什么，但您有资源和知识来为未知做好准备。看看您今年万圣节的文档工作——如果您保持警惕、组建团队并提前计划，您将准备好面对最可怕的威胁！

文章来源：Don’t Be Afraid of the Docs!