version-control - 如何应对软件文档和软件本身的版本控制？

Question

关闭。这个问题是opinion-based .它目前不接受答案。












想改进这个问题？更新问题，以便 editing this post 可以用事实和引用来回答它.

4年前关闭。




Improve this question




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

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

如果我现在正在为应用程序编写软件文档或用户指南，并且该软件本身具有版本控制，则可能会与文档和产品的版本号混淆:例如应用程序版本 1.5，文档版本 1.3。

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

Answer 1

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

我已经同意 Anders 的观​​点，相信软件和文档应该有不同的版本控制和版本控制系统。尽管相似且具有相同的目标，但文档和代码具有不同的生命周期，它们可以完全独立，仅在发布时映射到另一个。

至于为每个软件构建生成文档，问问自己:这真的有意义吗？文档是历史性的还是规范性的？每次构建生成的任何文档都更好地具有适当的工具来执行此操作。目前，这只适用于 API 文档，并且有 Doxygen-/Javadoc-style 工具来支持它。对于用户指南和安装指南来说，这可能永远都不可行，因为它们是上下文相关的。

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

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

分离文档和开发流程可以减少依赖关系，这是生产优质产品所需的基本指标。此外，需要后期绑定(bind)以最好地适应快速变化率和不可预测的事件，例如后期特征添加或删除。只有在最终版本(或 alpha-/beta 版本)时，文档版本才应映射到软件版本。但是，我同意 High-Performance Mark 的观点，即最终用户不应看到不同的版本号。文档版本号不需要出现在文档上。在文档过程中，这个数字可以被维护和向公众隐藏。

软件和文档版本控制可以同步维护的唯一情况是文档是开发过程的完全集成部分。在过去的 30 年中，我看到这种情况变得越来越少，因为与过去相比，正式的前期设计更少了，而是依赖于迭代的、快速的原型(prototype)设计方法来进行软件开发。最初由文档驱动软件开发的善意概念大多已被搁置，但新方法也没有为我们提供改进的文档或软件。无论文档是预先完成还是事后完成，开发商业质量产品所需的时间仍将增加一倍。