不要陷入黑暗：如何为安全团队构建更好的文档

大多数安全专家都会同意，详细的技术文档对于有效沟通和长期一致性至关重要。然而，编写文档通常被视为一项苦差事，会占用更高优先级任务的时间。文档是将高技术安全团队的工作流程结合在一起的粘合剂，支持高风险的客户可交付成果和紧迫的期限。因此，重要的是要优先考虑围绕编写文档建立快速、直接和高效的习惯。

无论如何在网络安全中使用文档，此博客都会提供一些技巧来简化流程，以便文档可以一次又一次地共享。遵循我们的用户流程指南，并将它们用作清单，以在编写黑客冒险经历时涵盖您的所有基础。要深入了解网络安全的技术写作元素和业内流行的首字母缩略词，我们建议下载我们流行的网络安全风格指南。

入门

首先，我们建议养成将黑客内容记录为笔记的习惯，因为这些将成为文档编制过程的基础。从项目的开始到结束做笔记是一个很好的习惯，你可以把它融入到你的日常生活中。在整个过程中做笔记可以让您捕捉重要的细节，并确保任何未记录的功能或“陷阱”都被考虑在内。否则，用户将被迫寻找其他资源以进一步了解全貌，这可能会导致挫败感并浪费时间。

没有具体推荐的笔记格式；但是，请准备好捕捉尽可能多的细节，因为从长远来看这将有所帮助。记下采取的每一个行动；复制有用的 URL 和代码块；关于您选择某种特定方法而不选择另一种方法的原因，以及您访问过的链接以获取更多信息。全部记录下来！

同样重要的是要考虑在哪里记录笔记，因为有效的笔记系统是整个过程的重要基础，将为您的成功做好准备。如果还没有使用Markdown，我们建议尝试使用它作为一种对黑客笔记进行分类的简单方法。为了获得更多收益，请将它与VSCode一起使用以进行动态动态渲染预览。查看这个Markdown 模板示例助您一臂之力，开始组织您的安全试验和磨难。这些是开始创建可单独使用或在整个团队中使用的高效文档的绝佳选择。通过这三个步骤的设置——一步是破解，一步是在 Markdown 中组织你的黑客笔记，另一个是在 VSCode 中呈现这些笔记——你就可以很好地创建详细而有影响力的文档。

定义用户流程

收集完内容后，应该研究如何快速且合乎逻辑地使用它。用户流是读者尽快找到所需内容的导航路径。不要担心您的团队已经在使用哪种软件解决方案来进行数字存储和组织（即 Docsify、ReadTheDocs、MkDocs、GitHub/GitLab 或 Atlassian），因为 Markdown 很容易在大多数解决方案中呈现。相反，专注于文档中可重复且可靠的用户流程来引导观众。用户的眼睛经常会扫描内容，导致他们错过关键信息。

基于研究的用户体验 (UX) 小组 Nielsen Norman Group 进行的一项多部分研究支持强大的用户流案例，该研究对 500 名参与者进行了 750 多个小时的数据眼动追踪评估，以分析他们的阅读方式数字内容。研究发现，在大约 25 年后，内容消费习惯几乎没有改变，而且，研究发现“人们仍然主要浏览，而不是阅读。扫描页面上的所有文本，甚至大部分文本，仍然极为罕见。即使用户确实扫描了整个内容，他们也永远不会完美地线性扫描它。”

左图：该研究最早的 F 模式实例之一，发现于 2000 年代初期，在 1900storm.com 上。右图：最近（2016/2017 年）F 模式的实例来自 Investopedia.com 上的后期研究用户根据呈现给他们的内容使用多种扫描模式。然而，对于网络安全团队中常见的文本密集型文档，读者最常使用的方法称为 F 形扫描模式。这种模式是用户从左到右、从上到下扫描内容的地方，重点是前几个词，当它们被呈现为大的、大多是未格式化的文本块时。

幸运的是，使用诸如 Markdown 之类的文档选项可以减轻一些模板和标准化语言的扫描负担，这样读者就知道会发生什么，也知道在哪里可以找到他们要找的东西。这与美化源代码有助于提高可读性和速度而不是试图将其消化为单个简介一样。

建立可靠的用户流程来引导用户

知道读者默认会快速扫描内容，我们可以以更有效地引导他们找到他们正在寻找的信息的方式构建我们的文档。

下面是制定的一些内容创建指南，这将有助于读者构建用户流。这样，他们就会知道会发生什么以及如何导航以找到他们需要的信息。我们建议采用以下技术：

首先创建大纲，强调可读性：

20-30 个单词的短句（如果你气喘吁吁，那就太长了）。

尽可能使用主动语态和动词（例如，The team found 20 vulnerabilities vs. 20 vulnerabilities were found）。

用结构写：

确保要点可以作为单一的想法或说明独立存在。

使用具有标题大小的层次结构来区分主要部分和次要部分。

使用链接到每个标题部分的目录。

优先考虑重要的事情，并直接：

保持标题具有描述性并与用户将要完成的任务相关。

与其说“有一个 X 可以用来完成 Y”，不如说“要完成 Y，使用 X”。这可能会让人觉得冷漠和不受欢迎，但请记住，用户正在寻找答案。他们正在寻找烹饪说明，而不是食谱背后的家庭故事。

请记住，这些是帮助他人完成任务的文档——为他们提供完成任务的步骤。

使用示例：

示例帮助用户了解他们如何使用在他们自己的情况下呈现的信息以及他们在每个步骤中可以期待什么。

代码块，尤其是当设置为正确的语言类型时，是展示示例的绝佳方式。

对于技术性较低的主题，请避免仅依赖嵌入式图像作为说明的一部分。这些是很好的视觉辅助和引导用户的方法，但图像抑制了内容索引和搜索功能。请务必写下图像中引用的步骤，因为这通过为包含的图像提供替代文本来帮助提高可访问性。

使用全球英语：

坚持指示性或命令性语气（事实或指示）而不是虚拟语气（希望、相信、建议、坚持）。

避免行话、口语、未定义的首字母缩略词、缩略语和缩写词。

避免使用模棱两可的代词，而是尽量做到具体。不要使用“那些”或“为他们中的每一个”，而是使用“为列表中的每个行项目”。

全球英语是一种精确、合乎逻辑和字面意思的写作方式，可以让非英语母语者更容易理解书面英语。

通过以下方式清楚地传达信息：

保持最新

文档之旅的最后一部分是计划如何使信息保持最新。那么，谁负责确保这些新生成的文档不会过时？在 Cosmos 团队中，我们在团队内部采用了“看到一些东西，更新一些东西”的策略，以消除文档过程中的单点故障。这确保整个团队都有起草和记录操作程序的经验，这也有助于我们记录团队中每个人可能并不明显的机构知识。

随着 Cosmos 服务的不断发展，我们正在测试新的文档和指南维护方法，以便在新团队成员继续加入该服务时找到最适合我们的方法。最近，我们一直在处理以下领域：

确保操作程序、代码库和工具中的约定都有明确的参与规则并被清楚地理解；

创建（并清楚地传达）贡献指南和编码最佳实践；

验证所有项目都包含自述文件（将文档保存在代码存储库中，这有助于简化更新）；

验证任何阻止程序是否作为票证或问题提交；

在工作管道中创建状态，提醒代码库更改和更新，并提醒团队成员注意质量保证更新；

使用更新计划和发行说明来确保团队同步功能修订和新的最佳实践，以及

验证在 Cosmos 服务中的团队每个人都知道对方在做什么，这加强了文档中的共同声音和项目方向。

单个团队成员很难自己找到所有错误和更新，并且需要不同的思维过程、技能组合和经验来创建和维护有效支持团队的文档。虽然上述建议可能并不完全适合组织，但将时间花在高质量的文档上确实会带来回报。GitHub Octoverse 最近的一份报告发现，“在开源项目和企业中，开发人员都看到了大约 50% 的生产力提升。”

你需要擅长文档

网络安全团队是其客户值得信赖的顾问，并且经常获得对组织最敏感数据的加速访问。因此，正确记录流程的每个步骤对于安全团队以有条不紊的方式安全运作并保护客户组织的安全至关重要。受托于组织的数字生计需要在任何安全参与的每个阶段都依赖逻辑、详细的文档，无论是渗透测试、产品安全审查、红队演习，还是支持持续的攻击性安全解决方案。

此外，擅长创建文档是一项技能，可以在不同的团队、安全学科甚至公司中使用。随着大辞职运动对我们的影响，安全团队的资源可能比以往任何时候都更加枯竭，因此您可以提供的任何额外技能都可能受到热烈欢迎。团队中总是需要知道如何跟踪细节的人。创建文档是与不同的人建立联系的好方法，因为在编写过程中定义了他们的角色或职责，否则可能无法与之密切合作。

全国网络安全等级测评与检测评估机构目录（6月6日更新）

本站仅提供存储服务，所有内容均由用户发布，如发现有害或侵权内容，请点击举报。