如何对设计文档进行最佳版本化？ [关闭]答案

【问题标题】：How to best version design documents? [closed]如何对设计文档进行最佳版本化？ [关闭]
【发布时间】：2010-10-04 21:37:39
【问题描述】：

之前有一些关于 SO（here 和 here）关于如何对 office 文档进行版本控制的讨论，但是我认为我的问题仍然有点不同。

我的编程项目从一个空的项目文件夹开始，除了一个名为“Design Documents”的子文件夹，其中包含项目功能规范的草稿，然后扩展为包含 API 规范或其他任何需要的内容。

当然，我也将这些文件检入到 SVN 中。 我正在寻找良好的文件格式和策略，以便在整个版本控制、差异和合并过程中发挥良好的作用。例如，我认为最好将文字处理器文件存储为 XML ，或者这些差异对于人类读者来说是丑陋和无用的吗？这是我想做的事情：

区分和合并文本文档（必备 OOo，必备 MS Word）
diff（也可能合并，尽管这在概念上可能会很困难）模式图，如 UML 图。我在想这些可能是独立的 XML/SVG 文件并链接到文本文档中，但我对这些文档的工作原理知之甚少，无法判断这是否真的可行。
在文本文档中显示自动更新的修订号（可能带有svn:keywords）

有人做过这种事吗？可能有一些关于 OOo 文件等的文档和教程，我可以查找，但我也很欣赏这些的指针，我主要是在寻找在实践中有效或无效的事情的第一手资料。

编辑： 可以肯定的是，这里不涉及“非技术用户”。它只是程序员，这些文档仅用于编程项目。可能会有要发布的 PDF 文件，但这只是另一个构建工件，不需要进行版本控制。

不过，我们真的不想使用 Tex 或类似的东西。我知道这很棒，但我就是不想为一个简单的文本文档而烦恼。我们必须学习它，正确获取所有额外的包，将 Tex-to-PDF 渲染添加到我们的构建过程等。这就像一个只有两三个文档的小编程项目。如果有的话，我宁愿使用 HTML，但文字处理器对我来说仍然是一个不错的选择，除了我想要好的版本控制。

还有一个想法：有没有类似 OOo 的 SVN 插件之类的东西？甚至，将 SVN 支持添加到 OOo 需要什么？就像“文件”菜单中的“同步”选项和“修订号”文本字段一样。我的意思是，这不会真正成为我们业务的一部分，但它会很酷，而且毕竟我是老板。

【问题讨论】：

那么，您最终是如何解决/应对这个问题的？

标签： svn version-control documentation

【解决方案1】：

WYSIWYG 编辑器（Word、OpenOffice）通常看不出任何其他人应该弄乱他们的文件的原因，因此找到一个非技术用户可以使用的编辑器和版本控制系统是不可能的。例外：git 有一个filter which can look into OpenOffice files。不过，我不确定您是否可以使用关键字扩展。

我建议使用 wiki 并为您的用户进行为期一周的培训如何使用它。它解决了您的所有问题（某些 wiki 甚至可以检查到版本控制系统中）。正如我在different post 中所说，唯一的障碍是用户需要几天时间才能习惯这个想法。之后，他们会喜欢的。

【讨论】：

【解决方案2】：

如果可能，我会将所有“原始”文件保留为文本格式（即 XML/DocBook、纯文本、LaTeX），以及在版本版本控制下渲染的 PDF。另外，我尝试使用 Subversion 存储库修订号作为文档的版本号。

如果您不能使用自动修订号（即在 Word 文档中），我建议使用最后修改日期。确保使用上次编辑的日期而不是当前日期宏，因为当前日期宏将填写您打印文档时的任何日期，这可能不是您想要的。另一种方法当然是使用传统的增量版本号，但根据我的经验，人们通常很难在只看到一个数字时知道哪个版本是最新的。人们通常更了解旧日期。

将日期和/或修订号作为每个页面的页眉/页脚的一部分也是一大优势，这样可以避免人们在办公桌上混淆不同的版本...

【讨论】：

【解决方案3】：

正如 Aaorn Digulla 所说，wiki 是个好主意。您必须意识到，真正实现您想要的目标的唯一方法是重新考虑您的整个文档策略。

没有软件可以解决文件格式不兼容以及无法比较不同版本的问题。您现在使用的工具不适合这项工作。改变你的工具集和你的思维方式会很困难、不舒服，而且可能很昂贵，但这是能够实现你想要的东西的成本，最终会为自己付出 10 倍的代价。

回想一下您最初在使用模式文档、UML 图，甚至是像规划 Word 文档这样简单的事情时遇到的困难。到目前为止，他们一直在努力，他们让你走到了这一步，但唯一真正的前进方式是继续使用专为你现在需要的工具而设计的工具现在。

注意：最终的解决方案可能不是 wiki，但也绝对不是您现在使用的。您需要进行一些探索并尝试一些事情。

【讨论】：

【解决方案4】：

在这里，wiki 似乎是个好主意，但如果不合适，您可能会考虑将Sphinx（或类似的）与ReStructured Text 结合使用。

虽然这也是一个“小型编程项目”，但它会为您提供 HTML 作为输出，同时保持差异的美观和可读性。我相信，设置它比使用 LaTeX 更容易。学习曲线会小很多；如果您将来需要 LaTeX 和 PDF，它就在那里等着您。

【讨论】：

【解决方案5】：

用于 SVN 的 TortoiseSVN 客户端 (Windows) 对 Open Office 有足够的了解，当您要求它对它们进行比较时，一旦它掌握了必要的版本，它就会在打开两个文档的情况下打开 Office，显示差异。我经常使用这个。我想那里还有更高级的解决方案，以及适用于 Mac/Linux/OS/360 或其他任何东西的类似解决方案，但对于这个经常因为想要午餐而感到非常不技术的用户来说，TortoiseSVN (http://tortoisesvn.tigris.org/) 提供了。

【讨论】：

【解决方案6】：

OOo 的问题在于文件格式实际上是一个 zip 压缩文件组（尝试将文件扩展名更改为 .zip 或 .7z）。这使得很难进行差异化。

我一直在研究 LaTex 和 DocBook，但是建立一个样式模板来使用是相当困难的。这是所有教程都掩盖的难点。

所以基本上我已经放弃了从文档中获取有意义的差异。它以二进制 blob 的形式签入。

【讨论】：

【解决方案7】：

我们使用 wiki 来获取我们一些项目的文档。它对每个条目都有很好的版本跟踪，但不是在文档级别，所以我们导出了文档并检查了基线。

【讨论】：