公司坚持在我们的所有文档中使用二进制格式

时间:2008-10-08 11:52:52

标签: documentation

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

  • 文档的差异版本互相攻击(所以同行评审它们很痛苦 - 因为我们所在的域名,所有更改的同行评审都是必不可少的)
  • Grep一个包含关键字文档的文件夹

您使用什么来编写文档?为什么?

也请给我弹药以改变这种状况......

19 个答案:

答案 0 :(得分:16)

我最近开始使用DocBook XML来编写我的文档。

在好的方面,它是一种纯文本格式。您可以将大型文档分成多个文件,并使用节点将它们整合到一本书中。自动生成目录和索引。文档内链接(在任意文本中,指向章节或章节)非常容易。只需按一下按钮,我就可以创建一个单html文件版本,一个chunked-html版本(每章一个文件)和一个PDF版本。

经过一些调整和定制后,我对输出非常满意。这些文件看起来很棒 !!

DocBook被真正的出版商广泛使用(最值得注意的是O'Reilly),并且它已存在超过15年,所以它达到了一定的成熟度。

另一方面,所有处理都是使用XSLT完成的,使用临时工具集。 (我自己的docbook管道包括Python,Java,Xerces,Xalan,Apache FOP和PDF-SAM。还有官方的XSLT样式表分发,以及我自己的XSLT自定义。)

DocBook不是一个交钥匙解决方案。如果不阅读手册,您将无法快速前进。如果你对XSLT一无所知,你就必须学习。

另一方面,编写文档时,您只需要知道十二个或两个XML标记。 (真正的专业知识在XML源代码生成期间发挥作用。)如果团队中的一个人愿意负责编写doc构建脚本,那么团队中的其他人都可以学习DTD并做一份体面的工作贡献。

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

“Subversion Book”是用DocBook编写的。这是一个包含不同书籍版本(单一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

答案 1 :(得分:8)

对于弹药,有可信赖的老实用程序员,第14章:纯文本的力量。

  

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

答案 2 :(得分:5)

Word对文档进行了更改跟踪(尽管它只能在您接受更改之前一直运行),并且您也可以对它们进行grep(文本未加密)。因此,我不确定你的论点是否会受到严格审查。我很乐意给你弹药改变这个但是随着年龄的增长,我变得厌倦和愤世嫉俗。

我们使用MS Word作为我们的文档(这是对早期选择的巨大改进(Lotus WordPro - 呃!)。

答案 3 :(得分:5)

我们使用维基(特别是Trac提供的维基),原因有两个。另外,如果我们真的需要,我们可以获得标记的文本版本并在纯文本环境中操作它(例如,在提交期间作为svn注释的一部分)。

一种可以轻松简化为纯文本(非二进制)的格式绝对是必须的。对于我们来说,能够将上转换到像PDF这样漂亮的格式对我们来说并不是非常重要。

答案 4 :(得分:4)

与Dylan的组织一样,我们也使用优秀的Confluence wiki。我写了一篇文章,说明为什么这是更好的方法Wiki is my word-processor,这应该给你一些改变这种情况的理由。

内部文档使用Wiki的好处包括以下内容。

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

如果你想要更多的弹药,那么The Atlassian Blog就会有很多维基促销。

答案 5 :(得分:4)

我们使用维基 - 特别是Confluence by Atlassian

这是一种商业产品,它很棒。我们通过免费/开放的wiki引擎选择它的原因之一是它有一个完整的WYSIWYG编辑器和各种其他功能,使熟悉Word的用户更容易访问它。

我们还提出了一个巧妙的技巧,我们在Subversion中存储图像,设计,线框等,然后通过Apache / SVN Web界面模块将wiki文档中的链接嵌入到这些资源URL中;如果您有兴趣,请注意我们如何执行此操作{/ 3}}。

答案 6 :(得分:3)

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

答案 7 :(得分:3)

文本格式有助于将文档与生成的项目(如JavaDoc,API参考或数据字典)合并。它也比word更好地扩展,这对于大型文档来说很难使用。最后,允许包含的格式允许多个作者同时处理文档。

LaTeXFrameMaker(我用过的两个系统)都具有非常出色的索引和交叉引用功能,并且具有原生文本格式或其原生格式的文本版本可以包含(在Framemaker的情况下为MIF)。它们也比单词更稳定。

我已经构建了工具来读取数据字典并生成可以包含在具有稳定索引和双向交叉引用的更大文档中的文档。 This product的功能规范用这种方式完成了LaTeX,让我再次与公司合作。我还使用FrameMaker开发了一个类似的过程。

答案 8 :(得分:2)

整个开发团队是否违反了这一要求,还是一个小团体?如果它是整个团队,只要忽略授权并使用基于文本的格式 - 这不会是员工第一次忽视愚蠢的规则。如果你过去没有对此大惊小怪,那就特别好用。如果您拥有,管理层可能会特别注意您的文档。

答案 9 :(得分:2)

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

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

也许Office 2007可能符合您的公司要求和您的顾虑?

答案 10 :(得分:2)

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

答案 11 :(得分:1)

他们是否坚持要您在Word中或仅以Word格式提供?您可以用文本格式编写并自动将其转换为Word。

答案 12 :(得分:1)

难道您不将文档文件存储在某种版本控制系统中,理想情况下是与源代码一起存储吗?我建议这样做(使得获取旧软件版本的文档变得容易)。

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

答案 13 :(得分:0)

另请查看DocBook的recommended toolchain(s)

答案 14 :(得分:0)

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

答案 15 :(得分:0)

自动化单词以将单词文档中的所有文本提取到文本文件中应该很容易。因此,您可以编写一个脚本,从word文档创建文本文件,以及grep,compare,版本控制,查看这些文本文件。

当然这不是一个理想的解决方案,因为你放弃了漂亮的格式,但它应该有用。

答案 16 :(得分:0)

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

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

答案 17 :(得分:0)

如果您使用Beyond Compare作为源控制系统的差异工具(正如我们所做的那样,使用Perforce),它将显示Word文档修订版之间的差异。不可否认,它只显示文本差异 - 格式更改未显示 - 但这通常足以让您看到更改的内容。

这只是投资Beyond Compare的另一个原因,因为它是我曾经使用过的最精美的软件之一 - 而且它是最好的30美元(如果你买几个,那就少)我花在软件上

答案 18 :(得分:0)

不要在这里为MS产品辩护,但MS word可以对文件进行区分。