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