我需要一些关于编写软件文档和用户指南的经验。
当我编写软件规范等正式文档时，每个文档都有一个版本号，并且在文档中的目录后面有一个更改历史记录，您可以在其中跟踪对文档所做的更改。
如果我现在正在为应用程序编写软件文档或用户指南，并且该软件本身具有版本控制，那么人们可能会对文档和产品的版本号感到困惑：例如应用程序版本 1.5，文档版本 1.3。
编写软件文档的常用方法/最佳实践是什么？您是否跟踪那里的文档更改？如果您打印更改历史记录 - 您是否显示产品和/或文档的更改？
【问题讨论】：
标签： version-control documentation versioning
我在每家工作过的公司都遇到过这个问题，即 1) 拥有重要的代码库，2) 尝试过专业质量的文档，以及 3) 拥有独立的开发和文档小组。
我已经同意 Anders 的观点，相信软件和文档应该有不同的版本控制和版本控制系统。虽然相似且目标相同，但文档和代码具有不同的生命周期，它们可以完全独立，仅在发布时映射到另一个。
关于为每个软件构建生成文档，问问自己：这真的有意义吗？文档是历史性的还是规范性的？每次构建生成的任何文档都更好地具有执行此操作的工具。目前，这只适用于 API 文档，并且有 Doxygen-/Javadoc-style 工具来支持它。对于用户指南和安装指南来说，这可能永远无法实现，因为它们是上下文相关的。
需要不同的版本控制系统，尤其是对于较新的结构化文档方法。结构化文档需要在比源代码更精细的粒度级别上进行管理，以便能够有效地处理一些看似简单的事情，比如重新命名；通常在段落、句子或单词级别进行管理，这与文件级别不同，这对于源代码来说已经足够了。此外，在多个产品或部门（工程、营销……）之间共享文档元素通常是经济的。而且，对于这种复杂程度的文档，只有内容管理系统就足以跟踪内容和管理变更； CVS-/SVN-/Perforce-/Clearcase 风格的 SCCS 根本不足以管理现实世界的文档。使用不同的版本管理工具可确保文档和软件的版本号不同。
如果考虑到处理拼写错误、语法错误和公司风格变化的需求，文档的变化率甚至可能比软件更高。
分离文档和开发流程可减少依赖性，这是生产优质产品所需的基本指标。此外，需要后期绑定以最好地适应快速变化率和不可预测的事件，例如后期特征添加或删除。只有在最终版本（或 alpha-/beta 版本）时，文档版本才应映射到软件版本。但是，我同意 High-Performance Mark 的观点，即最终用户不应该看到不同的版本号。文档版本号不需要出现在文档上。这个数字可以在文档过程中进行维护，并且对公众隐藏。
软件和文档版本控制可以同步维护的唯一情况是文档是开发过程的完全集成部分。在过去的 30 年中，我看到这种情况变得越来越少，因为与过去相比，正式的前期设计更少了，而是依赖于迭代的、快速的原型设计方法来进行软件开发。最初由文档驱动软件开发的善意概念大多已被搁置，但新方法也没有为我们提供改进的文档或软件。无论文档是预先完成还是事后完成，开发商业质量产品所需的时间仍会增加一倍。
【讨论】：
我认为文档和软件是不同的项目，每个项目都有不同的版本号。您希望能够更新文档而无需更新软件编号。我会把它命名为：
文档修订版 1.7
通过将软件版本和文档版本清楚地包含在同一个地方，应该不会有任何混淆。
【讨论】：
我们倾向于为我们的文档使用纯文本格式，主要是 LaTeX，并从修订的角度将其视为源代码：它进入 repo，我们可以做差异和补丁等。我们是对于已发布文档中的更改历史来说并不大，如果有必要，我们总是可以审计发生了什么，但很少这样做。
对于同步代码和文档版本号，我们首选的方法是文档的 v1.1.1 匹配软件的 v1.1.1，3.2.45 匹配 3.2.45 等等。然而，在实践中，我们通常只有前 2 位数字（即 1.1、3.2）的文档，因为第三位数字主要用于错误修复或性能增强。如果我们需要，使用 svn:keywords 将 repo 修订号插入到文档（和源代码中）。
我想告诉你，构建我们的新版本软件的同一个 makefile 也构建了新版本的文档，但我们还没有做到。不过，我们正在努力。
【讨论】：
您为什么不直接使用版本控制并将其用作自动文档修订？您可以让大多数系统在结帐时更新一些文本。
【讨论】：