Version control 如何处理软件文档和软件本身的版本控制？

我需要一些关于编写软件文档和用户指南的经验

当我编写像软件规范这样的正式文档时，每个文档都会得到一个版本号，并且在文档中目录之后会有一个更改历史记录，您可以在其中跟踪对文档所做的更改

如果我现在正在为某个应用程序编写软件文档或用户指南，而该软件本身有版本控制，人们可能会对文档和产品的版本号感到困惑：例如，应用程序版本1.5，文档版本1.3

---

编写软件文档的常用方法/最佳实践是什么？您是否跟踪文档的更改？如果打印更改历史记录-是否显示产品和/或文档的更改？

我认为文档和软件是不同的项目，每个项目都有不同的版本号。您希望能够在不必更新软件编号的情况下更新文档。我会把它命名为：

productX 1.3的系统文档 文件修订版1.7

---

通过在同一位置清楚地包含软件版本和文档版本，不应该有任何混淆。

为什么不使用版本控制并将其用作自动文档修订？您可以让大多数系统在签出时更新一些文本。

我们倾向于在文档中使用纯文本格式，主要是LaTeX，并从修订的角度将其视为源代码：它放在repo中，我们可以进行差异和补丁等。我们对已发布文档中的更改历史记录不感兴趣，如果有必要，我们可以随时对发生的事情进行审计，但很少进行审计

至于同步代码和文档版本号，我们首选的方法是文档的v1.1.1与软件的v1.1.1相匹配，3.2.45与3.2.45相匹配，依此类推。然而，在实践中，我们通常只有前两位数字（即1.1、3.2）的文档，因为第三位数字主要用于错误修复或性能增强。repo版本号使用svn:keywords插入到文档（和源代码）中，如果我们需要它的话

---

我想告诉你，构建我们新版本软件的同一个makefile也构建了文档的新版本，但我们还没有实现。然而，我们正在努力解决这个问题。

我在我工作过的每一家公司都遇到过这个问题：1）有重要的代码库，2）尝试专业质量的文档，3）有单独的开发和文档组

我同意Anders的观点，认为软件和文档应该有不同的版本控制和版本控制系统。尽管相似且具有相同的目标，但文档和代码具有不同的生命周期，这些生命周期可以是完全独立的，只能在发布时将一个映射到另一个

至于为每个软件构建生成文档，问问自己：这真的有意义吗？文件是历史性的还是规定性的？每个构建生成的任何文档最好都有相应的工具。目前，这只适用于API文档，并且有Doxygen-/Javadoc风格的工具支持它。对于用户指南和安装指南来说，这可能永远不可行，因为它们是上下文敏感的

需要不同的版本控制系统，尤其是对于较新的结构化文档方法。结构化文档需要在比源代码更精细的粒度级别上进行管理，以便能够有效地处理一些看似简单的事情，比如重新命名；通常在段落、句子或单词级别进行管理，与文件级别不同，文件级别对于源代码来说已经足够了。此外，在多个产品或部门（工程、营销等）之间共享文档元素通常是经济的。而且，对于这种级别的文档复杂性，只有内容管理系统足以跟踪内容和管理更改；CVS-/SVN-/Perforce-/Clearcase样式的SCCSs对于管理真实世界的文档来说是远远不够的。使用不同的版本管理工具可确保文档和软件的版本号不同

当考虑到处理打字错误、语法错误和公司风格变化的需要时，文档甚至可能比软件有更高的变化率

将文档和开发过程分离可以减少依赖性，这是生产高质量产品所需的基本指标。此外，后期绑定最好能适应快速变化和不可预测的事件，如后期特性添加或删除。只有在最终版本（或alpha-/beta版本）时，才应将文档版本映射到软件版本。但是，我同意High Performance Mark的观点，即最终用户不应该看到不同的版本号。文档版本号不需要出现在文档上。在文件编制过程中，可以保留该数字，并向公众隐瞒

只有当文档是开发过程中完全集成的一部分时，才能在lockstep中维护软件和文档版本控制。在过去的30年里，我看到这种情况越来越少，因为与过去相比，现在已经没有那么正式、预先的设计了，取而代之的是，依赖于迭代的、快速的原型方法进行软件开发。让文档驱动软件开发的最初善意的想法大部分被搁置一边，但新的方法也没有给我们改进文档或软件。无论文档是预先编写的还是事后编写的，都需要