编写技术文档的7个步骤
浏览：0
巴克励步
我经常碰到团队抱怨技术文档写不好——要么是信息太散，要么是开发者根本懒得看。其实，技术文档的撰写并不神秘，只要方法得当，完全可以成为产品体验的加分项。Baklib 的知识门户正好能帮团队沉淀这些内容，无论是内联网门户还是对外发布的开发指南，都能轻松管理。下面这份7步指南，会一步步拆解如何高效完成技术文档。 步骤1：为技术文档开发做准备技术文档的开发，应该从盘点你将用于写作过程的资源开始。简而言之，这
我经常碰到团队抱怨技术文档写不好——要么是信息太散，要么是开发者根本懒得看。其实，技术文档的撰写并不神秘，只要方法得当，完全可以成为产品体验的加分项。Baklib 的知识门户正好能帮团队沉淀这些内容，无论是内联网门户还是对外发布的开发指南，都能轻松管理。下面这份7步指南，会一步步拆解如何高效完成技术文档。
步骤1：为技术文档开发做准备
技术文档的开发，应该从盘点你将用于写作过程的资源开始。简而言之，这些资源可以分为几类：
- 受众
- 主题专家（SME）
- API 本身
就受众而言，你应该意识到有两类专家会看你的文档：
- 实施专家
- 开发者
根据 Infobip 的开发者教育者和技术写作者 Joanna Suau 的说法，实施专家会寻找你的 API 与他们在做的项目之间的良好契合点：
💛🧡🧡客户评价：我使用 Baklib 已有一年多的时间，我不得不说它满足了我的所有需求。目前我使用的是免费套餐，但很快就会用完，并升级到他们的付费套餐之一。就无头 CMS 而言，我发现 Baklib 简单直观，我喜欢通过他们的 API 将数据轻松拉入我的前端。他们内置的 Baklib 模板市场使构建和测试查询变得非常方便。我特别喜欢的一件事是继续尝试使用 Web Studio（一款很棒的前端开发工具，在我看来比 Web Flow 好得多），现在能够从 Baklib 中提取数据。
他们可能会查阅 API 参考进行评估。所以，一些概念性信息，比如最常见的 API 使用场景，以及工作流程，能很好地推广 API 并展示其潜力。
另一类受众是实际将 API 集成到他们工作流中的开发者。这意味着，作为受众研究的一部分，你最好调研一些可能受益于你的 API 的产品，并针对他们的需求定制用例，以便在文档中使用。
至于你需要的人力资源——主题专家，与参与 API 开发的人员沟通，采访他们，了解产品的一切细节，这很重要。看看专家们有什么好问题可以问。下面是技术写作者与 SME 讨论项目时常用的一组问题：
来源：Reddit
完成准备工作时，别忘了亲自访问 API 并探索它，了解它是如何运作的。毕竟，没有哪个写作者能在从未试用产品的情况下写出高质量的文档。一些可以帮助你理解 API 构成要素的东西包括设计文件、API 蓝图和 API 密钥。下面是一张 API 蓝图的截图，展示语法和这份资源有多描述性。
来源：I’d Rather Be Writing
记住，就文档而言，好的准备是成功的一半，所以给这个第一步足够的重视，技术文档后面几乎会自己写出来。
步骤2：决定写作风格
这个阶段与文档开发生命周期（DDLC）中技术文档的对应阶段非常相似，这意味着我们可以提取一些通用规则。首先是决定一个技术写作风格指南，它将指导你公司或这个项目后续所有技术文档的创建。风格指南有助于保持写作的一致性，并提供很好的指导，让文档的文本部分保持准确、切题，并尽可能对用户有用。如果你没有公司特定的内部风格，可以自由使用那些在线或纸质版本中可用的风格指南。例如，你可以使用详尽且极其有帮助的 Microsoft Writing Style Guide。
来源：Microsoft
你还需要一个参考来保持命名约定的一致。这很重要，因为如果使用多个术语表示同一个意思，用户可能会混淆。为此，你可以使用 Google 风格指南的 Word List 部分，它拥有我们见过的命名规则中最详尽的列表，并且迎合在作品中使用开发者行话的技术写作者。
来源：Google
最后但同样重要的是，你还应该决定你的技术文档将以何种格式呈现。有多种格式可选，其中一种非常流行的是三栏式，就像 Stripe 的技术文档那样。
来源：Stripe
目录位于左侧便于导航，中间是描述，右侧是代码示例，方便用户跟随解释。一旦你选择了写作风格，必须从头到尾保持一致，否则文档可能显得混乱且组织糟糕，这会严重损害文档的用户体验。
步骤3：在文档结构中添加关键元素
在开始阅读本章之前，请确保你也阅读了我们关于“技术文档不可或缺的元素”的博客。现在你有了关于 API 的足够信息和文档的框架，是时候开始思考你将填充哪些类型的内容了。这里的一个好做法是专注于为你的 API 提出常见用例，然后围绕它们创建文档。这种方法非常棒，因为访问你文档的感兴趣方很可能已经想到一个应用，正在寻找完全适合他们想法的解决方案。Google Maps 的 API 在这方面做得很好。它的文档被分成指南，解释一旦 API 集成到产品中，如何用它完成某些任务。
来源：Google Maps
例如，如果你需要在网站上显示静态地图，有一篇文章解释如何应用 API 来做到这一点。在你覆盖了所有用例之后，下一步是为初次接触 API 的用户提供一个起点。API 是复杂的产品，使用它们可能很快变得混乱，所以用一个 API 介绍和一个关于它如何工作的指南来引导用户开始是非常棒的。同样，Google Maps 的 API 树立了榜样。
来源：Google Maps
文档为进来的开发者提供了所有他们需要的理论和实践练习，以熟悉 API 并获得良好的第一印象。
来源：Google Maps
完成这个阶段所需的最后一个关键元素是文档大纲。大纲将帮助你指导写作，使工作更轻松，所以尽量详细，看看你是否能想出一个可以复用于库中大多数文档的文档大纲。例如，Spotify 的 API 文档在其许多文章中遵循了一个成功的公式。
来源：Spotify
文章的大纲涵盖了通用基础知识，如安装、响应、错误代码和认证。这里涵盖的信息为开发者提供了成功使用 API 所需的整套工具。在这个阶段你覆盖得越好，一旦你坐下来实际编写文档——这是过程的下一阶段——你的工作就越轻松。
步骤4：开发内容
这一步代表了技术文档写作过程的主体。在内容开发阶段，你做的所有准备将帮助你编写一致、准确且实际对使用 API 的开发者有用的内容。技术文档的特殊之处在于你开发的内容需要是双重的。第一部分是描述、解释和文本指南，你将编写这些内容来引导用户使用 API。毕竟，你是在为人写作，所以你必须提供优质、引人入胜的内容，帮助他们理解你的产品并成功使用它。在这里，你需要使用一些技术写作的最佳实践。看看 Twitter 的 API 文档。
来源：Twitter
这是一个出色的开发者内容示例，它超越了基本要求，让 API 看起来对用户友好，向开发者介绍了一个充满可能性的世界。要追随 Twitter 的优秀榜样，你只需要提醒自己是在为人写作，并使用对话式语言轻松传达你的观点。努力通过提供关于如何用 API 创造新事物的想法来激励你的读者。有时，你甚至可以使用幽默来缓和气氛，就像 GitHub 在其文档中所做的那样：
来源：GitHub
文档的另一部分是你将添加的代码，以说明你的写作，使其对开发者有用且可操作。API 文档的这一部分由代码示例组成，它们展示而不是告诉用户 API 的某个特定功能是如何工作的。你可能想将代码与你的描述和指南并行呈现，这样开发者可以立即看到某物如何工作，而不是仅仅阅读它。这就是 Stripe 的 API 文档的做法，并且它使用 Baklib 的多站点发布功能可以轻松实现。
