公司坚持对我们所有的文档使用二进制格式[关闭]答案

【问题标题】：Company insists on using a binary format for all our documentation [closed]公司坚持对我们所有的文档使用二进制格式[关闭]
【发布时间】：2008-10-08 11:52:52
【问题描述】：

我在一家公司工作，出于某种原因，该公司坚持我们所有的开发文档都应该是 MS Word 格式。作为二进制格式，这意味着我们不能：

不同版本的文档相互对照（因此同行评审很痛苦 - 由于我们工作的领域，所有更改的同行评审都是必不可少的）
Grep 一个文件夹，里面装满了关键字的文档

你用什么来写文档，为什么？

还请给我弹药来改变这种情况……

【问题讨论】：

MS word docx 格式不是二进制格式，如果您让它们转向新的 word 格式，您可以更轻松地对它们进行 diff 和 grep。
如果你的弹药不够用，word-doc-diff 可能对第 1 点有所帮助：softinterface.com/WDD/WDD.htm
@PintSizedCat docx 文件本质上是包含 XML 内容的 zip 文件，因此它们是二进制文件。即使您提取 XML，它们也是机器生成的密集 XML 文件，没有换行符。总而言之，对于 diff/grep 来说并非易事。

标签： documentation

【解决方案1】：

我最近开始使用 DocBook XML 来创作我的文档。

从好的方面来说，它是一种纯文本格式。您可以将一个大文档分成多个文件，并使用节点将它们全部组合成一本书。自动生成目录和索引。文档内链接（在任意文本中，指向章节或部分）非常容易。只需按一下按钮，我就可以创建一个单 html 文件版本、一个分块 html 版本（每章一个文件）和一个 PDF 版本。

经过一些调整和自定义，我对输出感到非常满意。这些文件看起来很棒！！

DocBook 被真正的出版商（最著名的是 O'Reilly）广泛使用，并且已经存在超过 15 年，因此达到了一定的成熟度。

另一方面，所有的处理都是通过 XSLT 完成的，使用了一组特别的工具。（我自己的 docbook 管道包括 Python、Java、Xerces、Xalan、Apache FOP 和 PDF-SAM。加上官方 XSLT 样式表分发，以及我自己的 XSLT 定制。）

DocBook 不是交钥匙解决方案。如果不阅读手册，您将无法快速上手。如果您对 XSLT 一无所知，则必须学习。

另一方面，编写文档时您真正需要知道的只有一打或两个 XML 标记。（真正的专业知识在从 XML 源生成文档时发挥作用。）如果您团队中的一个人愿意负责编写文档构建脚本，那么团队中的其他人都可以学习 DTD 并做得不错贡献。

无论如何... DocBook 肯定有一些缺点。这不是最简单的技术作者系统。但它是我所知道的最好的开源工具。

“Subversion Book”是用 DocBook 编写的。这是一个页面，其中包含指向不同书籍版本（single-html、chunked-html 和 PDF）的链接：

http://svnbook.red-bean.com/

这里是第一章 DocBook XML 源的链接，以便您了解它的工作原理：

http://sourceforge.net/p/svnbook/source/HEAD/tree/branches/1.7/en/book/ch01-fundamental-concepts.xml

【讨论】：

【解决方案2】：

对于弹药，有值得信赖的老实用程序员，第 14 章：纯文本的力量。

作为务实的程序员，我们的基础材料不是木头或铁，而是知识。我们收集要求为知识，然后表达我们的设计知识，实现、测试和文档。我们相信最好的格式持久存储知识是 纯文本。使用纯文本，我们给出我们自己操纵的能力知识，手动和以编程方式，虚拟地使用我们可以使用的所有工具。

【讨论】：

我不同意，因为上下文使纯文本更具信息性。例如，知道什么是标题、什么是段落、什么是方程式、什么是表格等，这使得解析和消化文档比纯文本更容易。纯文本没有要解析的规范或架构
纯文本并不意味着“没有规范或架构”。 Markdown、HTML、JSON、CSV 和源代码都是纯文本。
实用程序员+1。祝你好运，用程序员的书说服你尖头的老板，不过......
本章有很好的论据，对非程序员来说应该是有意义的。复印并粘贴在机上杂志中。 :-)

【解决方案3】：

出于您提到的两个原因，我们使用 wiki（特别是 Trac 提供的那个）。另外，如果我们真的需要，我们也可以获取标记的文本版本并在纯文本环境中对其进行操作（例如，在提交期间作为 svn cmets 的一部分）。

一种可以轻松简化为纯文本（非二进制）的格式绝对是必须的。对我们而言，能够将其上转换为漂亮的 PDF 格式并不是很重要。

【讨论】：

好主意，谢谢 - 但我怀疑我们希望能够上转换成漂亮的格式，有很多利益相关者有时必须查看我们的文档。
如果您想拥有一个 wiki，那么我建议您使用 dokuwiki。它以纯文本 nativeley 存储。另一方面，如果您需要记录软件的多个版本并且在 v1.0 和 v2.0 之间存在一些差异和一些共性，我不建议您使用 wiki。这在 wiki 中不容易做到。

【解决方案4】：

Word 具有文档更改跟踪功能（尽管它仅在您接受更改之前有效），您也可以对它们进行 grep（文本未加密）。所以我不确定你的任何一个论点都会受到审查。我很想给你弹药来改变这一点，但随着年龄的增长，我变得厌倦和愤世嫉俗。

我们在文档中使用 MS Word（这比之前的选择（Lotus WordPro - 啊！）有了很大的改进。

【讨论】：

是的，Word 的更改跟踪是我们进行审核的唯一方法。我没有意识到我能够 grep 文件...这将使我摆脱眼前的困境，谢谢:-)

【解决方案5】：

我们使用 wiki - 特别是 Confluence by Atlassian。

这是一个商业产品，非常棒。我们选择它而不是免费/开放的 wiki 引擎的原因之一是它具有成熟的 WYSIWYG 编辑器和其他各种功能，使熟悉 Word 的用户更容易访问它。

我们还想出了一个巧妙的技巧，将图像、设计、线框图等存储在 Subversion 中，然后通过 Apache/SVN Web 界面模块在 wiki 文档中嵌入指向这些资源 URL 的链接；如果您有兴趣，请联系here，了解我们如何做到这一点。

【讨论】：

【解决方案6】：

与 Dylan 的组织一样，我们也使用出色的 Confluence wiki。我写了一篇关于为什么这是更好的方法的文章，名为Wiki is my word-processor，它应该会给你一些改变这种情况的理由。

将 wiki 用于内部文档的好处包括以下内容。

文字处理器用户会被吸引到更改布局和排版，无论您的模板多么好，这会浪费时间并降低一致性。
wiki 提供全文搜索，您不太可能拥有所有人编写的 MS Word 文档正文。
wiki 提供文档版本历史；我从未听说过有一个团队成功地将所有修订保留在 Word 文档中，并且始终能够比较旧版本，或者使用版本控制系统（SharePoint 可能例外，但这是完全不同的失败场景）。
Wiki 使文档之间的超链接变得容易；在 Word 文档集合中的文档之间建立可靠链接太难了，因此新文档最终会将旧内容复制到新的单一文档中，这意味着它们需要更多时间来读写。
不同的wiki页面可以被不同的人同时编辑，Confluence可以在多人同时编辑同一个页面时合并更改；一次只有一个人可以编辑的 Word 文档更难协作。
像 Confluence 这样的 wiki 会根据 wiki 结构和标签自动生成导航页面；您需要图书管理员和严格的纪律才能浏览大量 Word 文档。
Wiki 页面的加载和显示速度通常比 Word 文档快。
维基页面有更多的自动元数据；您需要模板和规范，以确保 Word 文档始终在文档属性中设置标题、作者和版本，并且在屏幕上和打印中的文档中可见。

如果你想要更多的弹药，那么The Atlassian Blog 上有很多 wiki 推广。

【讨论】：

【解决方案7】：

您可以要求文档采用 OOXML（在 Word 的情况下为.docx）格式。但是，在我看来，它不像使用 ODT 那样理想，它仍然只是一个包含一堆 XML 文件的 zip 文件。 :-)

【讨论】：

有点吹毛求疵，它是一个 jar 存档 :)。 en.wikipedia.org/wiki/…
只是您的 nitpick 中的一个 nitpick：JAR 存档是 ZIP 文件。 en.wikipedia.org/wiki/JAR_(file_format)
来自您链接的网站：“JAR 文件基于 ZIP 文件格式。” （我的重点）。但是，是的，我想你找到了我。
次要...但是 grep 知道的足够多，可以窥视具有 docx 文件扩展名的 ZIP 文件吗？

【解决方案8】：

文本格式有助于将您的文档与生成的项目（如 JavaDoc、API 参考或数据字典）合并。它的扩展性也比 word 好得多，word 很难用于大型文档。最后，允许包含的格式允许多个作者同时处理一个文档。

LaTeX 和 FrameMaker（我为此使用的两个系统）都具有非常出色的索引和交叉引用功能，并且可以包含本机文本格式或它们本机格式的文本版本（ Framemaker 中的 MIF）。它们也都比 word 稳定得多。

我已经构建了可以读取数据字典并生成文档的工具，这些文档可以包含在更大的文档中具有稳定的索引和双向交叉引用。This product 的功能规范已经完成以这种方式使用 LaTeX 并让我在公司获得了另一场演出。我还使用 FrameMaker 开发了类似的流程。

【讨论】：

【解决方案9】：

是整个开发团队都反对这个要求，还是一个小团体？如果是整个团队，就忽略任务并使用基于文本的格式——这不是员工第一次忽略愚蠢的规则。如果您过去没有对此大惊小怪，则效果特别好。如果您有，管理层可能会特别关注您的文档。

【讨论】：

不幸的是，有些人（不再关心）——我猜他们只是像 Pax Diablo 所说的那样愤世嫉俗。我知道多年来我们有许多十字军试图改变这一点，但到目前为止都失败了（我猜没有管理层的支持）。

【解决方案10】：

MS Word 支持文档更改跟踪和同行评审。

新的 MS Office 格式完全基于 XML（要查看此内容，请将 MS Word .docx 文件重命名为 .zip，然后解压缩即可查看）。

也许 Office 2007 可能同时适合您的公司要求和您的顾虑？

【讨论】：

这是一个很好的观点，谢谢 - 我会检查一下。到目前为止，我们一直在使用 2003。

【解决方案11】：

您至少可以比较 Word 文档，查看“附加”菜单中的“跟踪更改”命令，或使用 DeltaView 之类的软件。通过谷歌搜索找到第一个链接at lifehacker.com。应该可以使用 Google Desktop Search 或其他类似的程序来搜索 word 文档，这些程序可以索引他们能够阅读的所有文件。

【讨论】：

【解决方案12】：

他们是坚持写在 Word 中还是只在 Word 格式中可用？您可以以文本格式书写并自动将其转换为 Word。

【讨论】：

我们必须使用一个模板，但我想这仍然是一种可能。谢谢，我会考虑的。
如果您在 Word 中提供它，然后经理说：“这是您的文档，我已经编辑了很多更改。”

【解决方案13】：

您是否将文档文件存储在某种版本控制系统中，最好与源代码一起存储？我建议这样做（便于获取旧软件版本的文档）。

如果您确实将文档存储在 VCS 中，您会注意到纯文本或基于 XML 的文件在这方面要好得多，因为您可以获得差异；此外，文本文件之间的更改通常比二进制文件之间的更改更有效地存储。

【讨论】：

【解决方案14】：

这里不是为MS产品辩护，但是MS word可以区分文档。

【讨论】：

捍卫 MS 产品有什么问题？
您说的是变更跟踪吗？确实，它会向您展示与上一或两个版本的区别，但它很快就会变得很麻烦，因此人们倾向于在开始处理文档之前接受所有更改，因此将修订版 2 与修订版 6 区分开来是很痛苦的。
实际上，Word XP/2002 添加了实际的文档差异。不知道它的效果如何，但它在某个地方的菜单上。
嗯...好的，我去钓鱼，谢谢。
我认为它首先出现在 Office 2003 中，但我不是 100% 确定。

【解决方案15】：

如果您使用Beyond Compare 作为源代码控制系统的差异工具（就像我们使用 Perforce 一样），它将显示您的 Word 文档版本之间的差异。诚然，它只显示文本差异 - 不显示格式更改 - 但这通常足以让您看到发生了什么变化。

这只是投资 Beyond Compare 的另一个原因，因为它是我用过的最精美的软件之一——而且它是我在软件上花费的最好的 30 美元（如果你买了几个则更少）

【讨论】：

【解决方案16】：

word 文档比较的工具有很多。我目前使用一个 python 脚本，它在 word 的内置比较和合并功能上放置一个命令行。

http://nicolas.lehuen.com/index.php/post/2005/06/30/60-comparing-microsoft-word-documents-stored-in-a-subversion-repository

【讨论】：

【解决方案17】：

自动将 word 文档中的所有文本提取到文本文件中应该很容易。因此，您可以编写一个脚本，从 word 文档创建文本文件，然后 grep、比较、版本控制、查看这些文本文件。

当然，这不是一个理想的解决方案，因为您失去了漂亮的格式，但它应该可以工作。

【讨论】：

【解决方案18】：

我认为有些程序可以将 Word 文档转换为纯文本。使用其中之一将单词 doc 转换为纯文本，然后使用 diff、grep 等

【讨论】：

【解决方案19】：

还可以查看 recommended toolchain(s) 获取 DocBook。

【讨论】：