⭐制作有效的文档

语境

我参与了一个项目，该项目最初的构想是为创作者提供一个平台，让他们在地图上构建包含点和目标的“体验”。最初的文档旨在以简化的方式向创作者解释其功能。

随着时间的推移，该项目逐渐演变成一个更加专注于事件（内部/外部）和业务的平台，从而导致功能数量大幅增加。

我们的项目内容丰富，功能齐全，但并非所有人都知道它的存在。为了解决这个问题，我们决定暂时停止开发，并为平台上的开发者和“创建者/管理员”（即公司社区团队成员）创建易于理解的文档。

最具挑战性的部分是开始。关键在于了解文档是为谁创建的以及其目的。

我们的文档已成为项目文档、用户手册和代码文档的混合体，从每个文档中提取相关内容以满足我们的需求。

这种格式很有帮助，为项目启动人员提供支持，并帮助管理部门了解目标和计划。

文档的组织可能由于各种原因而有所不同，并且这些变化通常反映组织的特定需求。

我坚信您所指的屏幕截图等视觉元素非常有效，并且如果有必要的话，图像中还可以用红色突出显示一些。

我知道这些技巧看起来非常显而易见，但你根本不知道我这辈子要读多少文档👀。通过采用清晰的命名方式，我们让文档更易于理解和使用，让用户在打开文件之前就能轻松找到所需内容并理解其内容。

确定主要主题：分析文档内容并确定主要主题或类别。它可能与特定功能、流程、模块或任何其他对您的应用程序或系统有意义的标准相关。
避免文件夹过深：保持文件夹结构不要太深。过多的嵌套文件夹会使导航变得困难。在本例中，我们最多使用了三个嵌套文件夹。
文件夹命名的一致性：就像文件命名一样，尝试保持文件夹命名的一致性。
全面而简洁：确保创建的类别涵盖广泛的主题，但避免过度细分。目标是使内容组织直观易懂。
逻辑关系：文件夹之间应该具有逻辑关系。例如，在我们的例子中，系统中用于创建项目的页面确实位于管理员面板和“库”部分中。
常规或介绍性文档：考虑设置一个包含常规或介绍性文档的初始文件夹。这有助于用户在深入研究更具体的类别之前了解概览。在我们的示例中，介绍位于“库”、“概览”、“页面”等部分。

风格一致：选择一种格式样式，例如字体、文本大小、颜色和标题样式，并在整个文档中保持一致。这将创建一个统一的视觉形象。我个人喜欢用红色突出显示我认为重要的方面以引起注意。
视觉层级：使用不同级别的标题来指示信息的层次结构。例如，一级标题可以表示主要部分，而较低级别的标题则表示子部分（如果你像我一样是前端开发人员，我知道你对这个主题很熟悉😂）。
列表和突出显示：使用编号或项目符号列表突出显示重要项目。对相关的单词或短语使用粗体或斜体。
足够的间距：创建并保持标准间距，因为没有人应该拥有这么大却空无一物的空间。
代码格式：如果文档包含代码片段，请使用一致的格式，以使代码易于理解。绝大多数平台都提供代码工具。
步骤编号：提供分步说明时，使用编号。

易读性和清晰度：本文档旨在方便不同受众（包括平台上的开发者、创建者/管理员）轻松理解。简洁的语言、屏幕截图等可视化资源以及重要信息的突出显示，有助于提升清晰度。

混合格式：项目文档、用户手册和代码文档的组合满足了用户的不同需求，为开发人员提供了详细的信息，为平台管理员提供了更全面的概述。

高效组织：文件夹和文件的结构逻辑清晰，遵循清晰的命名、按主题分类、详细的索引和导航链接等原则。这有助于查找信息和浏览文档。

格式标准：一致的风格、视觉层次、列表和高亮显示、充足的间距以及代码格式有助于提升阅读体验，使其更加愉悦易懂。这些标准有助于快速识别重要信息。

外部反馈：请项目外部人员阅读并使用文档，是识别可能存在混淆或不清晰之处的有效方法。这有助于持续调整文档，从而提高文档质量。

适应变化：文档的创建是为了响应项目的发展，并适应新功能和焦点的变化。这表明我们有能力随着项目的发展保持文档的相关性和更新性。

强调可用性：关注文档的可用性，考虑用户遵循说明时的体验，强调不仅提供信息而且确保用户能够有效使用信息的重要性。

总而言之，文档的可持续性是通过一种综合的方法实现的，这种方法考虑了用户的多样性，能够适应项目的变化，并采用了良好的组织和格式规范。这些要素有助于文档的有效性和持久性。

我尝试过评估文档复杂度的方法之一是，请一些之前从未接触过我项目的人员阅读文档，尝试理解其内容，并仅根据提供的说明有效地使用系统。事实证明，这种方法非常有用，因为它让我能够识别出可能不够清晰的部分，从而进行必要的调整。

特别感谢 X-team 允许我与大家分享我们项目的一些细节。我还要特别感谢 Lucas，他与我合作，为我们的项目创建了一份精彩的文档；还要感谢 Patrick，他仔细审阅了我的文字。

希望这篇文章对你有帮助！❣️