优秀开发者文档的必备特征
浏览：5
巴克励步
作为Baklib的研究员Ken，我常和团队讨论企业Wiki建设的痛点。很多公司投入大量时间写文档，但开发者却找不到、不爱用。问题的根源在于文档缺乏系统性设计——不仅是内容本身，更在于如何让信息在正确的时间被正确的人发现。企业Wiki不是简单的知识堆砌，而是一个可发现、可交互、持续进化的系统。我们需要像设计产品一样设计文档，从SEO到导航结构，从内容质量到交互方式，每个环节都要为开发者的实际工作流减负
作为Baklib的研究员Ken，我常和团队讨论企业Wiki建设的痛点。很多公司投入大量时间写文档，但开发者却找不到、不爱用。问题的根源在于文档缺乏系统性设计——不仅是内容本身，更在于如何让信息在正确的时间被正确的人发现。企业Wiki不是简单的知识堆砌，而是一个可发现、可交互、持续进化的系统。我们需要像设计产品一样设计文档，从SEO到导航结构，从内容质量到交互方式，每个环节都要为开发者的实际工作流减负。这才是Baklib在知识门户建设中反复强调的理念。
可发现性
你和团队花费数周甚至数月制作了出色的开发者文档，但开发者们并没有如你预期那样频繁使用。这怎么可能呢？很可能是因为你的开发者文档难以被找到。
首先，你需要确保当用户访问产品网站时，可以轻松找到文档链接。在首页顶部或底部放置一个链接就足够了。例如，Slack 就清晰展示了如何访问开发者文档。
虽然让文档链接可见很重要，但事实上，大多数用户并不会通过你的网站来访问文档。如今，大多数人通过搜索引擎在互联网上找到所需内容。在搜索栏输入几个关键词比浏览网站逐个查找要快得多。
💛🧡🧡客户评价：Baklib真的很容易使用。他们的团队总是反应迅速，随时提供帮助，使学习基础知识后，设置过程很简单。一个惊人的功能是能够导入任何现有文档，从而使迁移到平台更容易。他们的定制工具，用于设计和更新您的KB，提供我在任何地方都未见过的访问控制。我很欣赏文章如何相互关联并带有版本控制。
Mark Baker，影响深远的书籍《Every Page is Page One》的作者，曾写道：网站本身没那么重要，因为搜索引擎更看重单个页面。
这对开发者文档的可发现性意味着什么？意味着搜索引擎优化（SEO）至关重要。搜索引擎会返回指向特定页面的结果，以回答搜索查询。
让我们回到 Slack 的例子。如果一个开发者想通过谷歌搜索找到关于 Slack Events API 的文档，那么 Slack 必须确保其文档出现在搜索结果顶部。
如你所见，谷歌为好奇的开发者提供了多个与 Slack Events API 相关的链接，这表明 Slack 在 SEO 优化方面做得非常出色。
使用像 Baklib 这样的文档工具，可以借助其 SEO 元控制功能，将你的开发者文档推送到搜索引擎结果顶部。你可以调整 URL 键、标题、描述和预览图片，以提升文档的 SEO 表现。这些元素在 SEO 中各司其职。例如，修改标题可以优化 SEO 关键词，帮助文档页面获得更高排名。
最终，关键是要让开发者能够轻松找到所需资源。否则，所有的时间和精力都是徒劳。
可用性
优秀开发者文档的另一个重要特征是可用性。让我们探讨什么是可用的文档。
首先，不言而喻，你希望文档中提供尽可能多的信息。文档是开发者的信息来源，如果他们找不到所需内容，那么资源本身还有什么意义呢？
然而，这里就体现了可用性的重要性。文档中提供的信息量不应让读者感到不知所措或畏惧。虽然信息存在至关重要，但用户仍然需要能够在内容中找到方向。否则，他们会犹豫是否使用文档。
幸运的是，如果在文档中加入几个关键元素，其可用性将大幅提升。
首先需要记住的是，你的开发者文档不是一本书，用户不会像读书一样阅读它。正如技术作家兼多家科技公司创始人 Josh Fechter 所指出的，用户不会从头到尾阅读你的文档。他们会寻找特定信息，因此你应该相应地组织文档结构。
例如，我们来看看 GitHub 的 REST API 文档。左侧列出了 REST API 文档中的所有子类别和页面。右侧，每个页面都有一个目录，显示文档内容。
这些设计的目的是让导航更便捷，无论是在整个文档层面还是在具体文档内部。开发者文档中内容越多，这些导航元素就越有用。
此外，功能完善的搜索栏也很有帮助。在 GitHub 文档中，搜索栏位于右上角，随时可用。如果开发者想查找关于 REST API 部署的文档，搜索栏会给出结果。
结构化文档并提供导航方式对于开发者文档的可用性至关重要。开发者通常需要快速获取信息，他们会感激你通过精心组织和规划使其能够轻松访问。
质量
如果你问一百个开发者什么是高质量的开发者文档，可能会得到一百个不同的答案。然而，某些元素很可能会频繁出现。
准确性、完整性、可读性、连贯性和清晰度，这些都是高质量开发者文档的可靠标志，可以对各种经验和专业水平的开发者有所帮助。
简而言之，开发者使用文档来获取信息、学习并更好地完成工作。如果文档帮助他们在工作中表现更出色，那就说明资源非常出色。反之，如果文档导致他们做出错误决策或损害工作成果，那么其质量就不佳。
让我们聚焦于之前提到的高质量文档的几个要素，从准确性开始。
不言而喻，文档不应有语法错误。你可以通过使用 Grammarly 等工具来确保文本中没有错误。Grammarly 是一个强大的编辑器，能够指出语法错误和错误标点，同时提供句子结构改进建议、推荐更吸引人的用词、突出清晰度问题等。简而言之，它会分析文本并提出改进建议，使其更准确并优化你的写作风格。
说到写作风格、清晰度和易理解性，还有另一个值得一试的工具——Hemingway Editor。它的特定目标就是让写作清晰易读。
例如，我们看看 Vimeo 开发者文档中关于注册应用的部分。如果通过 Hemingway Editor 分析，可以看到分析结果以及工具是否提供改进建议。根据 Hemingway Editor，Vimeo 的文档可读性为 2 级，在 Hemingway 的评分标准中非常好。唯一的问题是两处副词“maybe”的使用，这也可以归因于 Vimeo 文档随意的写作风格。总体而言，之前提到的质量要素，如清晰度、简洁性和可读性，在这个例子中都达到了最高水平。
提供准确、易懂、清晰且文笔优秀的开发者文档，是你投入创建高质量资源的标志。借助上述工具只能让你的文档更上一层楼。
交互性
对于开发者文档而言，优秀的文笔只能做到一部分。一个真正出色的开发者资源还应该具备交互性。
我们并非暗示写作质量对开发者不重要；事实上，我们在前文中专门讨论了写作的重要性。然而，开发者是务实的，他们喜欢通过实践来学习。通过交云文档，他们可以立即尝试代码示例，验证想法。交互性可以通过可运行的代码示例、沙箱环境或 API 控制台来实现。这不仅提高了学习效率，还增强了文档的实用性。Baklib 支持富文本编辑和代码块，可以嵌入交互式组件，让文档真正活起来。
