I've encountered this issue at every company for which I've worked that 1) had a significant code base, 2) attempted professional quality documentation, and 3) had separate development and documentation groups.
I have come to agree with Anders, convinced that software and documentation should have different versioning and version control systems. Although similar and having the same target, documentation and code have different lifecycles, which can be fully independent, only being mapped one to the other at release time.
As for generating the documentation with each software build, ask yourself: does that really make sense? Is the documentation historical or is it prescriptive? Any documentation that is generated with each build better have the tools in place to do it. Currently, that only works for API documentation and there are Doxygen-/Javadoc-style tools to support it. That is likely to never be doable for User's Guides and Installation Guides because they are context sensitive.
The need for different version control systems holds, particularly, for the newer structured documentation methodologies. Structured documentation needs to be managed at a much finer level of granularity than source code to be able to efficiently handle something even as seemingly simple as rebranding; usually managed at either the paragraph, sentence, or word level, unlike the file level, which is sufficient for source code. Further, it is generally economical for document elements to be shared among multiple products or departments (engineering, marketing, ...). And, for this level of documentation sophistication, only a content management system is sufficient for tracking content and managing change; the CVS-/SVN-/Perforce-/Clearcase-style SCCSs are abysmally inadequate for managing real-world documentation. Using different version management tools ensures different version numbers for documentation and software.
Documentation may even have a higher rate of change than software when the need for handling typos, grammar errors, and corporate style changes is considered.
Separating documentation and development processes reduces dependencies, which is the fundamental metric needed for producing a quality product. Further, late binding is desirable to best accommodate the rapid rate of change and unpredictable events like late feature additions or deletions. Only at the moment of final (or alpha-/beta release) should the documentation version be mapped to the software version. But, I agree with High-Performance Mark that the end user shouldn't see different version numbers. The documentation version number does not need to appear on the document. That number can, within the documentation process, be maintained and hidden from the public.
The only time that software and documentation versioning can be maintained in lockstep is when documentation is a fully-integrated part of the development process. Over the last 30 years, I've seen this becoming less and less the case because there is less formal, upfront design than there used to be, relying, instead, on an iterative, quick-prototyping approach to software development. The original well-intentioned notions of having documentation drive software development have mostly been put aside but the new methodology also hasn't given us improved documentation or software. Whether the documentation is done upfront or as an afterthought, it's still going to double the time it takes to develop a commercial-quality product.
I think that the documentation and the software are different items, which each have different version numbers. You want to be able to update the documentation without having to update the software number. I would have named it something like:
System Documentation for productX 1.3
Documentation revision 1.7
By clearly including both the software version and the document version in the same place there shouldn't be any confusion.
We tend to use a plain text format for our documentation, mainly LaTeX, and treat it just like source code from a revision point of view: it goes in the repo, we can do diffs and patches, etc. We're not big for change histories in published documents, we can always audit what has gone on if necessary but it rarely is.
As for synchronising code and documentation version numbers, our preferred approach is that v1.1.1 of a document matches v1.1.1 of the software, 3.2.45 matches 3.2.45 and so on. However, in practice we often only have documentation for the first 2 digits (ie 1.1, 3.2) since the third digit is mainly for bug-fixes or performance enhancements. The repo revision number is inserted into the documentation (and in the source code) using svn:keywords should we ever need it.
I'd like to tell you that the same makefile which builds our new version software also builds the new version of the documentation, but we haven't got there yet. We are, however, working on it.
发布评论
评论（4）
我在我工作过的每家公司都遇到过这个问题，这些公司 1) 拥有重要的代码库，2) 尝试专业质量的文档，3) 拥有单独的开发和文档小组。
我同意 Anders 的观点，相信软件和文档应该有不同的版本控制和版本控制系统。虽然相似且具有相同的目标，但文档和代码具有不同的生命周期，它们可以完全独立，仅在发布时相互映射。
至于为每个软件构建生成文档，请问自己：这真的有意义吗？该文档是历史性的还是规定性的？每次构建生成的任何文档都最好有合适的工具来完成它。目前，这仅适用于 API 文档，并且有 Doxygen/Javadoc 风格的工具来支持它。对于用户指南和安装指南来说，这可能永远无法实现，因为它们是上下文相关的。
对不同版本控制系统的需求尤其适用于较新的结构化文档方法。结构化文档需要以比源代码更精细的粒度进行管理，以便能够有效地处理看似简单的事情，例如品牌重塑；通常在段落、句子或单词级别进行管理，这与文件级别不同，文件级别对于源代码来说已经足够了。此外，在多个产品或部门（工程、营销等）之间共享文档元素通常是经济的。而且，对于这种级别的文档复杂性，仅内容管理系统就足以跟踪内容和管理变更； CVS-/SVN-/Perforce-/Clearcase 风格的 SCCS 远远不足以管理现实世界的文档。使用不同的版本管理工具可以确保文档和软件的版本号不同。
当考虑到处理拼写错误、语法错误和公司风格更改的需要时，文档的更改率甚至可能比软件更高。
将文档和开发流程分开可以减少依赖性，这是生产优质产品所需的基本指标。此外，需要后期绑定以最好地适应快速的变化率和不可预测的事件，例如后期功能添加或删除。仅在最终版本（或 alpha-/beta 版本）时才应将文档版本映射到软件版本。但是，我同意高性能标记的观点，即最终用户不应该看到不同的版本号。文档版本号不需要出现在文档上。在记录过程中，可以保留该数字并对公众隐藏。
只有当文档完全集成到开发过程中时，软件和文档版本控制才能保持同步。在过去的 30 年里，我发现这种情况越来越少，因为与以前相比，现在的正式设计和前期设计越来越少，而是依赖于迭代的快速原型方法来进行软件开发。最初用文档驱动软件开发的善意想法大部分已被搁置，但新的方法也没有给我们带来改进的文档或软件。无论文档是预先完成还是事后完成，开发商业质量产品所需的时间仍然会增加一倍。
I've encountered this issue at every company for which I've worked that 1) had a significant code base, 2) attempted professional quality documentation, and 3) had separate development and documentation groups.
I have come to agree with Anders, convinced that software and documentation should have different versioning and version control systems. Although similar and having the same target, documentation and code have different lifecycles, which can be fully independent, only being mapped one to the other at release time.
As for generating the documentation with each software build, ask yourself: does that really make sense? Is the documentation historical or is it prescriptive? Any documentation that is generated with each build better have the tools in place to do it. Currently, that only works for API documentation and there are Doxygen-/Javadoc-style tools to support it. That is likely to never be doable for User's Guides and Installation Guides because they are context sensitive.
The need for different version control systems holds, particularly, for the newer structured documentation methodologies. Structured documentation needs to be managed at a much finer level of granularity than source code to be able to efficiently handle something even as seemingly simple as rebranding; usually managed at either the paragraph, sentence, or word level, unlike the file level, which is sufficient for source code. Further, it is generally economical for document elements to be shared among multiple products or departments (engineering, marketing, ...). And, for this level of documentation sophistication, only a content management system is sufficient for tracking content and managing change; the CVS-/SVN-/Perforce-/Clearcase-style SCCSs are abysmally inadequate for managing real-world documentation. Using different version management tools ensures different version numbers for documentation and software.
Documentation may even have a higher rate of change than software when the need for handling typos, grammar errors, and corporate style changes is considered.
Separating documentation and development processes reduces dependencies, which is the fundamental metric needed for producing a quality product. Further, late binding is desirable to best accommodate the rapid rate of change and unpredictable events like late feature additions or deletions. Only at the moment of final (or alpha-/beta release) should the documentation version be mapped to the software version. But, I agree with High-Performance Mark that the end user shouldn't see different version numbers. The documentation version number does not need to appear on the document. That number can, within the documentation process, be maintained and hidden from the public.
The only time that software and documentation versioning can be maintained in lockstep is when documentation is a fully-integrated part of the development process. Over the last 30 years, I've seen this becoming less and less the case because there is less formal, upfront design than there used to be, relying, instead, on an iterative, quick-prototyping approach to software development. The original well-intentioned notions of having documentation drive software development have mostly been put aside but the new methodology also hasn't given us improved documentation or software. Whether the documentation is done upfront or as an afterthought, it's still going to double the time it takes to develop a commercial-quality product.
我认为文档和软件是不同的项目，每个项目都有不同的版本号。您希望能够在不更新软件编号的情况下更新文档。我会将其命名为：
productX 1.3 的系统文档
文档修订版 1.7
通过在同一位置明确包含软件版本和文档版本，就不会有任何混淆。
I think that the documentation and the software are different items, which each have different version numbers. You want to be able to update the documentation without having to update the software number. I would have named it something like:
System Documentation for productX 1.3
Documentation revision 1.7
By clearly including both the software version and the document version in the same place there shouldn't be any confusion.
我们倾向于为我们的文档使用纯文本格式，主要是 LaTeX，并从修订的角度将其视为源代码：它位于存储库中，我们可以进行差异和补丁等。如果需要更改已发布文件中的历史记录，我们总是可以审核所发生的事情，但很少这样做。
至于同步代码和文档版本号，我们首选的方法是文档的 v1.1.1 与软件的 v1.1.1 匹配，3.2.45 与 3.2.45 匹配，依此类推。然而，在实践中，我们通常只有前 2 位数字（即 1.1、3.2）的文档，因为第三位数字主要用于错误修复或性能增强。如果我们需要的话，可以使用 svn:keywords 将存储库修订号插入到文档（以及源代码中）中。
我想告诉您，构建新版本软件的同一个 makefile 也构建了新版本的文档，但我们还没有做到这一点。不过，我们正在努力解决这个问题。
We tend to use a plain text format for our documentation, mainly LaTeX, and treat it just like source code from a revision point of view: it goes in the repo, we can do diffs and patches, etc. We're not big for change histories in published documents, we can always audit what has gone on if necessary but it rarely is.
As for synchronising code and documentation version numbers, our preferred approach is that v1.1.1 of a document matches v1.1.1 of the software, 3.2.45 matches 3.2.45 and so on. However, in practice we often only have documentation for the first 2 digits (ie 1.1, 3.2) since the third digit is mainly for bug-fixes or performance enhancements. The repo revision number is inserted into the documentation (and in the source code) using svn:keywords should we ever need it.
I'd like to tell you that the same makefile which builds our new version software also builds the new version of the documentation, but we haven't got there yet. We are, however, working on it.
为什么不直接使用版本控制并将其用作自动文档修订？您可以让大多数系统在结账时更新一些文本。
Why don't you just use version control and use that as the automatic document revision? You can have most systems update some text on checkout.