创建有效的技术文档

这三个 C 构成了技术写作的核心原则。它们可以帮助您在制作高质量文档方面取得长足进步。

为了在写作中实现清晰度，请应用以下指南

• 使用简单的词语和清晰的语言。请记住目标受众，尤其是如果其中包括非英语母语者。
• 明确谁需要执行操作。用主动语态写作并非严格要求。但是，当您需要明确谁需要执行操作时，应该使用它。例如，阐明函数是由事件触发还是用户需要显式调用函数。
• 清晰地介绍和解释新术语。这有助于为文档后面涵盖的概念奠定基础。
• 为了避免歧义，请明确指定代词。

  如果“it”、“this”和“these”在给定上下文中可以指代多个事物，则用适当的名词替换它们。

• 每个句子表达一个意思，以提高可读性。
• 每个段落表达一个主要意思。段落中的每个句子都应该在逻辑上与前面的句子相关联。想象一下，如果段落中的每个句子都是链条中的一个环节。如果您拿起第一个环节，链条中的其他环节应该依次排列，形成一个连续的序列。句子之间的关联方式也应如此，确保单个意思的流畅表达。

保持句子简短。这会自动提高文档的可读性和清晰度。也有助于快速理解。由于结构复杂，长句子可能更难以快速理解。

有关句子长度和可读性策略的更多见解，请参阅简单句子（位于https://readabilityguidelines.co.uk）和流行的可读性公式，包括维基百科上的 Flesch-Kincaid 指数。

在整个文档中使用相同的术语，以确保无缝的阅读体验。例如，如果您开始将“用户代理”称为浏览器，请始终如一地使用该术语。这避免了由于交替使用词语而可能产生的混淆，即使这些词语具有相同的含义。

此外，在整个文档中保持一致的单词大小写并遵循统一的格式样式。这些做法不仅增强了可读性，还有助于专业呈现您的文档。

应用与组织代码相同的原则来组织内容：花一些时间设定明确的目标并思考文档所需的结构。确保每个小节都逐步为实现此目标做出贡献。

在引言中，首先描述您要记录的特性。接下来，通过解释了解该特性对读者有何益处来设定上下文。这可能包括描述该特性在现实生活中可能很有用的场景。您为主题添加的相关性越多，读者就越容易理解和参与内容。

以下问题可以帮助您确保内容在逻辑上得以推进

• 您的文档结构是否可以引导读者从基础概念到更高级的概念？是否有部分内容介绍“什么”以建立基础，然后深入探讨“为什么”和“如何”？考虑文档结构是否反映了该主题的自然学习路径。使文档结构与学习的自然进程相一致，有助于读者逐步构建知识，并增强整体学习体验。
• 在概念部分之后是否有足够的入门指南或示例？
• 考虑内容的流程。它是否遵循逻辑顺序——从一个句子到下一个句子，从一个段落到下一个段落，以及从一个部分到下一个部分？每个部分是否在逻辑上建立在之前提供的信息之上，避免内容出现突然跳跃或空白？

此外，在处理草稿时，始终问问自己

• 我用这个句子回答了读者哪些问题？
• 我能否添加一个简单的或现实的用例来解释这个概念？

想象一下，您坐在某人旁边，向他们解释这些概念。预测他们的问题并在写作中解决它们。使用这种方法尽可能多地添加相关示例。

添加示例时，不要局限于代码；包括非代码场景以演示特性的实用性。这有助于读者更好地理解概念，并迎合不同的学习风格。考虑提供现实世界的场景或用例来说明特性或概念如何在实际情况下应用。

评估文档的结构，以确保其保持逻辑和平衡的层次结构。

• 确保每个部分和小节都有明确的目的和足够的内容。
• 查找主部分仅包含一个小节（孤儿）的情况，例如 H2 部分下只有一个 H3 部分。这表明您需要重新组织内容或进行一些补充。
• 检查是否存在较低级别的标题，例如 H4。太多的小节会让读者不知所措，使他们难以掌握信息。在这种情况下，可以考虑将内容以项目符号列表的形式呈现，以帮助读者更有效地记住关键要点。这种方法有助于简化层次结构，也有助于更轻松地导航。
• 虽然每个部分都应有足够的内容，但请注意整体长度。如果任何部分变得过长，可能会让读者不知所措。将较大的部分拆分为多个逻辑小节，或将内容重组为新的部分和小节。将内容分组为易于消化的部分有助于保持专注并改善读者的导航。

一个不容忽视的方面是自我审查和校对所写内容的重要性。无论您是创建大型文档还是简短的段落，此步骤都至关重要。

花时间全面审查您的工作将有助于您识别流程不畅或可以改进清晰度的部分。在自我审查期间，旨在发现并删除冗余（重复想法而不增加价值）和重复（过度使用单词或短语）。这些改进将确保您的文档清晰连贯，并按预期传达您的想法。

校对，然后休息一下再进行审查。只有这样才能提交您的作品。虽然拼写检查器可以标记拼写错误，但它们可能无法标记单词的错误使用，例如无意中使用“he”代替“the”。最好休息一下，以全新的视角返回来发现可能错过的任何错误。密切注意识别语气、风格、时态或格式方面的不一致之处，并进行必要的调整。

为了提高文档的清晰度和可访问性，还要牢记以下指南和提示。要深入了解任何主题，请随时查阅我们的写作风格指南。

• 项目符号列表与编号列表：总的来说，列表使文档更易于扫描。当项目没有特定顺序时，使用项目符号列表。当需要按特定顺序执行步骤时，使用编号列表。在开始列表之前始终包含引导句以提供上下文。
• 逗号：在引导从句后使用逗号以提高可读性和阐明句子结构。使用逗号分隔列表中的项目以确保清晰度。
• 替代文本：始终为添加到内容中的图像提供替代文本。这使使用屏幕阅读器的用户能够访问您的文档。除了图像外，请确保视频和音频文件带有相应的描述性文本。
• 描述性链接文本：确保每个链接文本即使脱离上下文也清晰明了，并清楚地表明链接指向何处。描述性链接文本还有助于使用屏幕阅读器的人理解链接的目标。例如，使用“阅读我们的写作风格指南以了解更多信息”而不是“单击此处以了解更多信息”。
• 包容性语言：让您的文档对所有人充满吸引力。努力使用尊重和认可受众多样性的词语。

本文到此结束。我希望您发现这些提示对快速复习技术写作最佳实践有所帮助。请记住，学习如何创建有效且易于使用的文档是一个持续的过程。它始于了解您的受众和文档的目标。通过应用这些技术写作原则和技巧，您一定能够增强文档的清晰度和整体质量。

如果您学到了新东西或有任何想法引起您的共鸣，请告诉我。我还想了解您在技术文档工作流程中使用的任何最佳实践。请在Mastodon或Discord上与我们分享。