如何最好地版本控制设计文档?

11

在SO上曾有关于如何对办公文档进行版本控制的讨论(这里这里),但我认为我的问题还有些不同。

我的编程项目始于一个只有一个名为“设计文档”的子文件夹的项目文件夹,其中包含该项目的功能规格草案,并随后扩展以包含API规格或其他所需内容。

当然,我也会将这些文件提交到SVN中。 我想要的是与整个版本控制、差异比较和合并流程相协调的良好文件格式和策略。例如,我认为将文字处理程序文件存储为XML可能是最佳选择,但差异对于人类读者而言是否难以阅读?以下是我想要做的事情:

  • 比较和合并文本文档(必备OOo,最好有MS Word)
  • 比较(可能还要合并,尽管这可能在概念上比较困难)模式图,例如UML图。我想这些可以是独立的XML / SVG文件,并链接到文本文档中,但我不太了解这些文档的工作方式是否可以实现。
  • 在文本文档中自动显示更新的修订版本号(可能使用svn:keywords

有人已经做过这种事吗?可能有许多关于OOo文件等的文档和教程可以查阅,但尽管我也赞赏这些指针,我主要是寻找在实践中可行或不可行的第一手资料。


编辑: 为确保没有“非技术用户”参与,这里只涉及程序员,文档仅用于编程项目。可能会有要发布的PDF文件,但那只是另一个构建工件,无需进行版本控制。

尽管如此,我们真的不想使用TeX或类似工具。我知道它很棒,但对于简单的文本文档,我就是懒得去学习,调好所有额外的包,将TeX转换成PDF并添加到我们的构建过程中等等。这将像为两三个文档创建一个小型编程项目。如果有什么的话,我宁愿使用HTML,但文字处理器仍然看起来是一个不错的选择,除了我需要良好的版本控制之外。

还有另一种想法:是否有适用于OOo的SVN插件或反之亦然?甚至,为向OOo添加SVN支持需要做些什么呢?例如在“文件”菜单中添加“同步”选项和“修订号”文本字段。我的意思是,那不会真正成为我们业务的一部分,但这很酷,毕竟,我是老板。


那么,你最终是如何解决/应对这个问题的? - Tobias Kienzler
7个回答

4
WYSIWYG编辑器(如Word、OpenOffice)通常不认为其他人应该干扰他们的文件,因此找到一个非技术用户可以使用且友好于版本控制系统的编辑器是不可能的。例外情况:git有一个过滤器,可以查看OpenOffice文件。我不确定是否可以使用关键字扩展。我建议使用维基和一周的培训来帮助用户学习如何使用它。这解决了所有问题(一些维基甚至可以被检入版本控制系统)。正如我在另一篇文章中所说,唯一的障碍是用户需要几天时间来适应这个想法。之后,他们会喜欢它。

3
在可能的情况下,我会将所有“原始”文件保存为文本格式(即XML / DocBook,纯文本,LaTeX),除了版本控制下的渲染PDF。此外,我尝试使用Subversion存储库修订号作为文档的版本号。
如果您无法使用自动修订号(即在Word文档中),我建议使用上次修改的日期。请确保使用最后编辑的日期而不是当前日期宏,因为当前日期宏会填入打印文档时的任何日期,这可能不是您想要的。当然,另一种方法是使用传统的增量版本号,但根据我的经验,人们通常很难知道哪个版本是最新的,仅看到一个数字时。人们通常更清楚旧日期。
在每一页的页眉/页脚中包含日期和/或修订号也是一个很大的优点,这样您就可以避免人们混淆桌子上散落的不同版本...

2
正如Aaorn Digulla所指出的,维基是一个好主意。您必须意识到,您真正想要实现自己的目标的唯一方法就是重新思考整个文档策略。
没有任何软件可以解决不兼容的文件格式和无法比较不同版本的问题。您现在使用的工具不适合这项工作。更换工具集和思考方式可能会很困难、不舒服,甚至可能很昂贵,但这是实现您想要的成果的代价,这将使您得到10倍的回报。
回想一下您最初处理架构文档、UML图和甚至规划Word文档时遇到的困难。这些工具一直使用到此时此刻,并且使您走到了这一步,但前进的唯一真正方式是转向为您需要的工具。
注意:最终的解决方案可能不是维基,但它肯定不是您现在正在使用的工具。您需要探索一下并尝试一些新的东西。

2
“一个Wiki在这里似乎是个好主意,但如果不太适合,您可能想考虑使用Sphinx(或类似工具)和ReStructured Text

虽然这也需要进行“一点编程项目”,但它会为您提供HTML作为输出,同时保持差异性良好且易读。我相信设置它的难度比LaTeX小得多,学习曲线也要小得多;如果将来需要LaTeX和PDF,它可以满足您的需求。”


2
TortoiseSVN客户端(Windows)的SVN已经了解足够多的关于Open Office的知识,当你要求它对它们进行差异比较时,一旦它获得必要的版本,它会打开Office并显示两个文档之间的区别。我经常使用这种方法。我想象中还有更高级的解决方案,以及类似的Mac/Linux/OS/360等操作系统的解决方案,但对于这个非常技术性的用户来说,他经常感到非常不专业,因为他想吃午饭,TortoiseSVN(http://tortoisesvn.tigris.org/)是一个好选择。

0

OOo的问题在于文件格式实际上是一组被压缩的文件(尝试将文件扩展名更改为.zip或.7z)。这使得进行差异比较变得困难。

我一直在研究LaTex和DocBook,但建立一个可用的样式模板非常困难。这是所有教程都忽略的难点。

所以基本上我已经放弃了从文档中获取有意义的差异。它作为二进制块被检入。


0
我们在一些项目的文档中使用了维基。它可以很好地跟踪每个条目的版本,但不能在文档级别上进行版本控制,因此我们将文档导出并作为基线进行检查。

网页内容由stack overflow 提供, 点击上面的
可以查看英文原文,
原文链接