如何编写软件文档
浏览：1
巴克励步
我常常和产品团队、研发团队讨论文档协作的痛点。很多企业把知识库当成“文档垃圾场”，扔进去就再也不管——既没有结构化，也没有持续维护。真正的文档体系应该是活的，就像 Wiki 一样可以随时编辑、更新、关联。Baklib 的企业 Wiki 建设方案，就是帮团队快速搭建一个可协作、可发布的知识中枢，让技术文档不再是“写一次就封存”的静态文件，而是随产品迭代持续生长的资产。下面这篇关于软件文档编写的指南，从
我常常和产品团队、研发团队讨论文档协作的痛点。很多企业把知识库当成“文档垃圾场”，扔进去就再也不管——既没有结构化，也没有持续维护。真正的文档体系应该是活的，就像 Wiki 一样可以随时编辑、更新、关联。Baklib 的企业 Wiki 建设方案，就是帮团队快速搭建一个可协作、可发布的知识中枢，让技术文档不再是“写一次就封存”的静态文件，而是随产品迭代持续生长的资产。下面这篇关于软件文档编写的指南，从风格规范到工具选型，都值得做文档的团队反复看。
软件文档是必不可少的：如果你生产软件，就应该为它提供文档支持。
把文档看作是将软件所包含的一切翻译成通俗语言的一种方式。
有了合适的文档，利益相关者可以确保软件符合他们的期望，用户可以使用软件，开发人员可以沟通以构建软件。
💛🧡🧡客户评价：Baklib真的很容易使用。他们的团队总是反应迅速，随时提供帮助，使学习基础知识后，设置过程很简单。一个惊人的功能是能够导入任何现有文档，从而使迁移到平台更容易。他们的定制工具，用于设计和更新您的KB，提供我在任何地方都未见过的访问控制。我很欣赏文章如何相互关联并带有版本控制。
相反，如果没有合适的文档，软件可能就像天书一样——没有人愿意费力地翻阅代码来了解你想要实现什么。
正如 Mike Pope 所说：“如果没有文档，它就不存在。”
因此，在本文中，我们将重点介绍一些撰写高质量文档的技巧。
选择一份风格指南
在编写软件文档时，你需要保持一致性。标准化的术语加上不变的格式，能让你的文档更易读。
这对你的受众来说意义重大，因为他们不需要进行脑力劳动就能理解文本。例如，你的日期格式是什么？
是使用 2022年6月14日，还是 June 14, 2022？或者是 06/14/2022？
避免在三个选项之间切换，而是保持一致的风格。这将让你的文本易于理解，证明你的专业性。
但你要如何记住使用哪种格式？另外，你应该使用美式英语还是英式英语？
这些问题的答案可以在风格指南中找到。风格指南是技术写作者的圣经——一个关于写作风格所有问题的单一参考点。
风格指南通常包含以下主题的指南：
- 语法和标点
- 格式规范
- 术语使用
- 语气和风格
这样，如果你不确定如何编写软件文档，可以随时查阅公司的风格指南。
话虽如此，如何获得一份呢？整理风格指南是一项耗时的任务，考虑到你手头还有其他事情，感觉有些多余。
幸运的是，你不需要从头开始构建——许多风格指南都是公开可用的。
选择一个最适合你公司的，然后根据公司实践进行编辑。Scott DeLoach 和 Mike Unwalla 在下面解释了这种方法。
换句话说，最好选择一个符合你业务实践的风格指南，然后在有意义的方面完善那些指南。
即使是微软也使用外部来源；他们的标点条目将你引向 The Chicago Manual of Style。
所以，在选择风格指南时，选择一个与你的公司最相关的。
例如，如果你的公司以组织良好、结构清晰的格式和明确的标题及子章节为傲，那么 Google 的风格指南是理想的。
如果你想确保你的业务保留风格指南中的信息并应用内容指南，可以采用 Apple 的指南。
这个风格指南充满了图片和视觉元素，是最以受众为中心的，也最具吸引力。
四处看看，看看哪个指南最适合你的公司——我们写过一篇博客文章，介绍了6个令人印象深刻的技术写作风格指南，你应该去看看！
选择合适的文档工具
软件和软件文档是相辅相成的。没有合适的文档工具，软件可能就像个黑盒子。
文档打破了不透明性，让开发人员和用户可以检查软件如何运行，这极大地促进了代码的维护和应用。
你可以把文档称为新软件的“小抄”。
为了促进这种协作和透明度，仅仅将文档托管在个人电脑上是不够的。
相反，它们必须在一个公共空间中易于所有相关方——开发人员、最终客户、利益相关者等——访问。
Nicholas Zakas 也强调了可访问库的重要性。
拥有这样一个承载所有信息的库，开发人员可以免去无休止的 Slack 滚动，用户也不必为寻求答案而发送电子邮件。
你的受众节省了大量时间，因为每个人都知道去哪里找到他们需要的东西。
在选择软件文档库工具时，要考虑你公司的需求——你希望这个功能具体做什么？为了弄清楚这一点，问自己一些问题，例如：
- 谁将是文档的主要受众？
- 需要支持哪些内容类型？
- 协作需求是什么？
- 集成要求是什么？
考虑你的业务需求，列出必需功能，然后整理出一系列问题。
在决定工具时，这些问题是选择最佳选项的指南。
例如，如果易于沟通是你看重的，那么 Freshdesk 和 HelpDocs 应该从你的列表中划掉。
尽管它们有许多其他优点，但两者都不允许添加内部评论。
Baklib 支持此功能。你可以提及团队成员以查看、分享或更新知识，甚至可以嵌入评论，促进协作。
甚至可以在评论线程中嵌入文档，为你的同事提供方便的参考点。
同样，如果你重视集成能力，Bloomfire 和 Guru 不是好的选择，尽管它们有其他品质。
这两个平台的集成选项有限，而其他平台则拥有更高数量的集成。
另一个例子是文档历史记录。如果这对你和你的客户至关重要，Baklib 允许你查看文档的完整历史记录，最长可达12个月。
软件会突出显示更改了什么，如果需要，你可以恢复到旧版本。
访问文档的完整历史记录是一个巨大的优势，因为你可以看到更改发生的时间和原因。
万一这些更改不应该被做出，那么撤销它们也很容易。
以下是与软件文档工具相关的两篇推荐阅读：
1. 所有优秀软件文档工具都具备的7个常见特性
2. 软件文档工具的优势
包含 ReadMe 文件
ReadMe 文件是软件文档的关键组成部分；很合适，因为它的名字字面上就在大喊着让你读它。
这个文档概述了一个软件项目，为你提供项目的基本信息。如果不确定某个软件解决方案是否有用，阅读 ReadMe 应该能解决这个难题。
一份好的 ReadMe 应该回答以下五个问题：
- 这个项目做什么？
- 为什么这个项目有用？
- 如何开始？
- 在哪里可以获得帮助？
- 谁为这个项目做出了贡献？
一旦你简洁地回答了这五个问题，你就可以确信该文档达到了它的目的。
ReadMe 是某人在遇到你的项目时首先查看的文件，用来决定它是否与他们相关。
考虑到这一点，一份完美的 ReadMe 是简洁的，只要够长，以便开发人员可以判断项目是否合适。对于冗长的详细文档，Wiki 是更好的选择。
下面是一个极其简短的 ReadMe 示例。
在这个极简的 ReadMe 中，你可以立即了解要点。它展示了使用、配置和安装，几秒钟内就可读完。
读者只需几个词就能确切知道他们在处理什么。
在一个更标准的 ReadMe 中，理想情况下应包含以下内容：
- 项目标题
- 描述
- 安装
- 配置设置
- 使用
- 测试
- 协作者
- 贡献指南
- 许可证
如果 ReadMe 最终比预期的要长，那么包含一个目录以便于导航也是一个好主意。
以下是一个包含上述所有元素的 ReadMe 示例。
这个 ReadMe 拥有我们之前提到的所有内容：一开始，它向用户介绍其功能，然后深入一个包含多个资源的广泛目录。
它还很好地使用了徽章。
徽章不是必需的，但它们是一个很好的资源——为读者提供关于你的软件的一目了然的信息片段。
它们也证明你了解自己在做什么。查找徽章的起点是 shield.io。
如果你不确定如何开始编写 ReadMe，有许多在线工具和模板可以帮助你。
