创建有效的技术文档

有效的特性文档对于提升用户使用该特性的体验至关重要。好的文档就像拼图中的一块，能让一切都清晰明了——这是鼓励用户采纳特性的关键。

为了帮助您创建有效的技术文档，本文概述了技术写作的核心原则。同时，它还重点介绍了创建清晰易懂的文档的最佳实践。运用这些技术写作原则有助于我们保持 MDN 内容的高质量。无论您是记录自己的项目或产品，还是在各种环境下为技术内容做贡献，都可以通过遵循这些最佳实践来提高工作质量。

力求清晰、简洁、一致

这三个“C”（Clarity, Conciseness, Consistency）构成了技术写作的核心原则。它们能帮助您在撰写高质量文档方面取得长足的进步。

清晰性 (Clarity)

为实现写作的清晰性，请遵循以下指南

使用简单的词语和清晰的语言。请牢记您的受众，特别是当其中包含非英语母语者时。
明确谁需要执行操作。严格来说，不必强制使用主动语态。但是，当您希望明确谁需要执行操作时，应该使用它。例如，请明确是事件触发了某个函数，还是用户需要显式调用该函数。
清晰地介绍和解释新术语。这有助于为后续文档中的概念奠定基础。
为避免歧义，请清楚地指定代词。

如果“it”、“this”和“these”在特定语境中可能指代不止一个事物，请用专有名词替换它们。
力求每句话只表达一个观点，以提高可读性。
每段只坚持一个主要观点。段落中的每个句子都应该与其前面的句子在逻辑上相关联。想象一下，段落中的每个句子都是链条中的一个环节。如果您拿起第一个环节，链条中的其他环节应该会依次连接，形成一个连续的序列。句子之间就应该这样连接，确保单个想法的流畅过渡。

简洁性 (Conciseness)

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

根据常见的可读性标准，目标是每句 15-20 个单词。

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

一致性 (Consistency)

在整个文档中使用相同的术语，以确保读者体验的无缝衔接。例如，如果您开始将“用户代理”称为浏览器，请始终保持该术语。这可以避免因交替使用意义相同但词语不同的词语而造成的混淆。

此外，在整个文档中保持一致的词语大小写和统一的格式风格。这些做法不仅能提高可读性，还能使您的文档呈现出专业性。

有条理地组织内容以获得最大效果

在组织内容时，应用与组织代码相同的原则：花一些时间设定明确的目标，并考虑文档的预期结构。确保每个子部分都逐步地为实现这一目标做出贡献。

从引言开始

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

有逻辑地推进

以下问题可以帮助您确保内容进展有条理

您的文档结构是否能引导读者从基础概念到更高级的概念？是否有部分介绍“是什么”以建立基础，然后再深入探讨“为什么”和“怎么做”？考虑文档结构是否能反映该主题的自然学习路径。将文档结构与自然的学习过程相匹配，有助于读者循序渐进地构建知识，并提升整体学习体验。
概念性部分之后是否有足够的操作指南或示例？
考虑内容的流程。它是否遵循逻辑顺序——从一个句子到下一个句子，从一个段落到下一个段落，从一个章节到下一个章节？每个章节是否都逻辑地建立在之前呈现的信息之上，避免内容突然跳跃或出现空白？

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

这句话我是在回答读者的哪个问题？
我能添加一个简单的或现实生活中的用例来解释这个概念吗？

包含示例

想象一下，您正坐在一旁向某人解释概念。预见他们的疑问并在您的写作中解答。利用这种方法添加尽可能多的相关示例。

添加示例时，不要仅限于代码；包含非代码场景来展示特性的实用性。这有助于读者更好地理解概念，也能迎合不同的学习风格。考虑提供现实世界的场景或用例，来说明该特性或概念在实际情况中的应用。

优化文档结构和长度

评估您的文档结构，确保其保持逻辑和均衡的层级。

确保每个章节和子章节都有明确的目的和足够的内容。
查找主要章节只包含一个子章节（孤节）的情况，例如 H2 章节下只有一个 H3 章节。这表明您需要重新组织内容或进行一些补充。
检查是否有更低级别的标题，如 H4。过多的子章节会让读者感到不知所措，难以理解信息。在这种情况下，考虑将内容呈现为项目符号列表，以帮助读者更有效地记住要点。这种方法有助于简化层级结构，也方便导航。
虽然每个章节都应该有足够的内容，但也要注意整体长度。如果任何章节变得过于冗长，会让读者感到不知所措。将大型章节拆分成多个逻辑子章节，或将内容重组为新的章节和子章节。将内容分组为易于理解的小块有助于保持专注并改善读者的导航。

仔细校对您的文章

有一个方面怎么强调都不为过，那就是对您所写内容进行**自我审查**和**校对**的重要性。无论您是在创建长篇文档还是短段落，这一步都至关重要。

花时间全面审查您的作品将帮助您找出那些流程不顺畅或可以改进清晰度的部分。在自我审查期间，目标是发现并消除冗余（不增加价值的观点重复）和重复（过度使用词语或短语）。这些改进将确保您的文档清晰连贯，并按预期传达您的想法。

校对，然后休息一下，再进行第二次审查。之后再提交您的工作。拼写检查器可以标记拼写错误，但可能无法标记词语的错误使用，例如意外地将“he”用作“the”。最好休息一下，用清新的视角回来，捕捉您可能错过的任何错误。请密切注意识别语气、风格、时态或格式上的一致性问题，并进行必要的调整。

其他建议

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

项目符号列表与编号列表：列表通常使文档更易于扫描。当项目没有特定顺序时，使用项目符号列表。当步骤需要按特定顺序执行时，使用编号列表。在开始列表之前，始终包含一个引导句以提供上下文。
逗号：在引入性从句后使用逗号，以提高可读性并理清句子结构。在列表中分隔项目时使用逗号以确保清晰性。
替代文本：始终为您添加到内容中的图片提供替代文本。这使得使用屏幕阅读器的用户也能访问您的文档。除了图片，请确保视频和音频文件附有描述性文本。

描述性链接文本：确保每个链接文本在脱离上下文时也能清晰明了，并清楚地指示链接指向何处。描述性链接文本也有助于屏幕阅读器的用户理解链接的目标。例如，使用“阅读我们的写作风格指南以了解更多”而不是“点击这里以了解更多”。

包容性语言：让您的文档对所有人都是受欢迎的。努力使用尊重和承认受众多样性的词语。

总结

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

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