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