如何编写技术文档计划
浏览：2
巴克励步
我经常看到团队一上来就扑进代码里写文档，结果写出来的东西要么没人看，要么看了也看不懂。问题出在哪？出在没计划。产品手册建设不是把代码注释复制粘贴一遍，而是需要像设计产品一样设计信息的交付方式。一个靠谱的技术文档计划，能帮你厘清读者是谁、写什么、怎么写、用什么工具。Baklib 的多站点发布机制让文档不仅能内部协作，还能一键发布为对外的产品手册，真正让文档成为产品体验的一部分。下面这份经典指南，值得每
我经常看到团队一上来就扑进代码里写文档，结果写出来的东西要么没人看，要么看了也看不懂。问题出在哪？出在没计划。产品手册建设不是把代码注释复制粘贴一遍，而是需要像设计产品一样设计信息的交付方式。一个靠谱的技术文档计划，能帮你厘清读者是谁、写什么、怎么写、用什么工具。Baklib 的多站点发布机制让文档不仅能内部协作，还能一键发布为对外的产品手册，真正让文档成为产品体验的一部分。下面这份经典指南，值得每一个要做产品手册的团队收藏。
明确目标读者
创建高质量技术文档计划的第一步是确定你为谁而写。谁会阅读这份文档计划？
例如，为公司内部的产品经理写与为外部利益相关者写有很大区别。前者可能熟悉公司的标准流程和工作流，而后者可能对这些概念完全陌生。另一方面，如果你的文档计划是为你的技术写作团队准备的，那么它可以相当非正式，但可能比面向高层管理时更详细。
要确定文档计划的目标读者，请问自己以下问题：
💛🧡🧡客户评价：总体而言，Baklib 在部署灵活性方面对我来说是一个改变游戏规则的工具。该工具是一种混合云解决方案，适合我们的环境及其复杂性。我喜欢这些块的多功能性，它们可以在一个地方用于创建、测试和部署它们。更详细的指标对于跟踪活动和确保一切正常非常有用。支持团队也非常友好，总是愿意帮助解决可能出现的任何问题。
- 谁会从这份文档中受益？
- 他们需要知道什么？
- 他们目前的知识水平如何？
回答这些问题时想到的员工和同事很可能对文档计划感兴趣。因此，请根据他们的视角和专业知识进行调整。
同时，还要考虑技术知识。你的读者对术语的熟悉程度如何？他们能理解常见的软件文档术语吗？这些都是编写文档计划时需要评估的关键因素。但作为一般规则，最好遵循专业作家 Jory MacKay 的建议：
技术写作的首要规则是：“不可假设。”对你来说显而易见的内容，对读者可能并非如此，所以你需要站在他们当前的知识水平上。
换句话说，你应该注意他们的技术熟练程度。即使只有一位非技术读者，也最好谨慎行事。解释首字母缩写词，避免使用缩写，并花时间讲解技术概念。你文档计划的读者会感激这一点。
界定文档计划的范围
在确定你为谁而写之后，接下来要确定你写什么。文档计划将涉及哪些内容？哪些主题必须包含？相反，有没有可以省略的主题？换句话说，你需要界定文档计划的范围。
例如，你将编写一份适用于所有项目的通用文档，还是为某个特定项目定制？文档计划是否涵盖测试文档以及标准技术文档？仅定义这些参数对技术写作人员来说就非常有帮助。知道写作范围就成功了一半；有了明确的指导方针，实际的写作过程会很快。
哈佛大学教授 J. Richard Hackman 也认为：“设定明确的工作范围是团队高效运转的关键。” 如果技术写作人员知道既定范围，他们在编写文档计划时就能更高效。而且，受益的不只是他们——为什么不也告知你的读者呢？这样，他们就知道预期内容，并能轻松判断该计划是否对他们有益。塔克教授 Scott D. Antony 也建议采用这种做法：“在文档开头插入目录或范围声明，读者就能迅速判断出文档的价值。” 在文档计划开头放置一个简短的说明，告诉读者文档中包含什么，他们就能快速判断这份文档是否有用。
创建文档计划大纲
范围确定后，你就可以开始构建文档计划的结构了。最简单的方法是创建大纲——一份内容组织方式的草稿。这样的大纲确保文档计划逻辑清晰，不会出现随意的主题切换，每个部分都能自然地衔接。
构建大纲时，尝试使用倒金字塔方法论。这种信息架构策略首先阐明最重要的见解，然后分支到细节，最后列出次要信息。在你的文档计划中，金字塔的底部可能包括文档的目的、范围和目标，然后再深入具体细节。然后，在文档计划的末尾，你可以包含术语表、参考文献等——金字塔的尖端。关于在大纲中包含哪些内容，可以参考下图，它列出了文档计划的标准组成部分：
文档计划至少应包含以上列出的部分。它们包含在大多数文档计划中，是构建你自己文档的良好起点。此外，该图遵循了倒金字塔结构：先覆盖基本信息（封面、联系信息、摘要），然后深入细节，如技术文档规范。遵循这些指南和建议，你可以轻松创建出色的文档计划大纲。
确定计划的合适格式
定义文档计划大纲后，你必须决定如何呈现这些信息。选择什么字体？使用项目符号列表还是编号列表？你会使用图表吗？展示信息的方式有无数种，因此你必须为文档计划选择最佳格式类型。
最简单的起点是排版。通常，两种字体系列是衬线字体和无衬线字体。衬线字体包含装饰性尖角，而无衬线字体由干净的线条组成，没有装饰。由于其直线线条，无衬线字体被认为更正式，常用于商业场合。因此，这种字体更适合你的文档计划。如果你的公司相对现代，正文可以使用衬线字体，但标题应保持无衬线。这样，文档的主要标识看起来会更专业。
关于内容本身，考虑加入图表。有时通过视觉传达信息比文字更好，因为读者通常更容易处理图像。例如，云架构师 Lynn Langit 在她的文档中使用图表：“我在图表方面取得了很好的效果。我为不同受众定制视图，例如客户流程视图、开发人员视图、DevOps 视图等。此外，我喜欢将图表区域涂成红、黄、绿三种颜色，以快速显示状态。” 通过颜色和定制等用户友好的元素，图表使你的文档计划更易于理解。例如，想象描述文档审查过程：难道通过图表说明这一过程的各个阶段，而不是写出每一个细节，不是更容易吗？如你所见，为文档计划确定合适的格式可以带来天壤之别。
评估可用资源
格式类型确定后，你的下一个任务是确定你的文档能力。换句话说，你应该评估你可用的写作资源。人力资源可以说是最关键的因素，因为你需要知道谁能贡献这些文本。例如，你有多少技术写作人员？他们能覆盖工作量吗？有没有开发人员可以帮忙？谁将是你的主题专家和审阅者？认真回答这些问题，因为它们直接关系到谁能影响文档。
关于技术资源，首先评估你的硬件。你的服务器是否有足够的磁盘存储和内存？你可能会使用 Visual Studio Code 和 Adobe Photoshop 等强大工具，因此这些技术规格至关重要。硬件之后，验证你可用的软件。你将使用哪些工具？如何截图？哪个拼写检查软件最好？但首先，确保你有一个高质量的文档工具。这类解决方案至关重要，因为它们极大地促进了整个文档流程。例如，Baklib 提供协作编辑、版本管理和多格式导出等功能，让你能高效地创建和管理技术文档计划。
Baklib帮助企业建立Community社区平台，为企业构建多个“内容输出窗口”，用于承载企业产品发布、更新动态、教程、活动、会议、资源、问答以及客户互动的内容平台。并且还能实现企业与客户、客户与客户、企业与企业间基础社区拥有的强交互性，比如点赞、评论、转发、分享等。
