documentation - 公司坚持对我们所有的文档使用二进制格式

Question

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

文档的不同版本（因此同行评审很痛苦——因为我们工作的领域，所有更改的同行评审都是必不可少的）
grep 一个包含关键字文档的文件夹

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

也请给我弹药来改变这种情况......

score 16 · Accepted Answer

我最近开始使用 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

score 8 · Accepted Answer

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

作为务实的程序员，我们的基础材料不是木头或铁，而是知识。我们将需求收集为知识，然后在我们的设计、实现、测试和文档中表达这些知识。我们相信持久存储知识的最佳格式是 纯文本。有了纯文本，我们就可以使用几乎所有可用的工具手动和编程操作知识。

score 5 · Accepted Answer

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

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

score 5 · Accepted Answer

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

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

score 4 · Accepted Answer

与 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 文档始终在文档属性中设置标题、作者和版本，并且在屏幕上和打印中的文档中可见。

如果您想要比这更多的弹药，那么Atlassian 博客上有很多 wiki-promotion 。

score 4 · Accepted Answer

我们使用一个 wiki，特别是 Atlassian 的Confluence。

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

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

score 3 · Accepted Answer

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

score 3 · Accepted Answer

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

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

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

score 2 · Accepted Answer

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

score 2 · Accepted Answer

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

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

也许 Office 2007 可能既适合您的公司要求，也适合您的顾虑？

score 2 · Accepted Answer

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

score 1 · Accepted Answer

您不将文档文件存储在某种版本控制系统中，理想情况下与源代码一起存储吗？我建议这样做（可以轻松获取旧软件版本的文档）。

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

score 1 · Accepted Answer

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

score 0 · Accepted Answer

0

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

于 2008-10-08T11:58:21.823 回答

score 0 · Accepted Answer

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

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

score 0 · Accepted Answer

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

score 0 · Accepted Answer

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

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

score 0 · Accepted Answer

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

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

score 0 · Accepted Answer

0

还可以查看推荐的 DocBook 工具链。

于 2010-02-15T17:08:39.990 回答

documentation - 公司坚持对我们所有的文档使用二进制格式

19 回答 19

Related

Reference