我在一家公司工作,出于某种原因,该公司坚持我们所有的开发文档都应该是MS Word格式。作为二进制格式,这意味着我们不能:
- 文档的不同版本之间存在差异(因此同行评审是一件痛苦的事情——由于我们工作的领域,所有更改的同行评审都是必不可少的)
- 在装满文档的文件夹中查找关键字
你用什么来写文档?为什么?
还请给我弹药来改变这种情况。。。
我最近开始使用DocBook XML编写文档。
从好的方面来说,它是一种纯文本格式。您可以将一个大型文档分解为多个文件,并使用节点将它们合并到一本书中。目录和索引是自动生成的。文档内链接(在任意文本内,指向章节或章节)非常容易。只需按下一个按钮,我就可以创建一个html文件版本、一个分块的html版本(每章一个文件)和一个PDF版本。
经过一些调整和定制,我对输出非常满意。这些文档看起来很棒!!
DocBook被真正的出版商(最著名的是O’Reilly)广泛使用,它已经存在了15年多,所以它已经达到了一定的成熟度。
另一方面,所有的处理都是用XSLT完成的,使用一组特殊的工具。(我自己的文档库管道包括Python、Java、Xerces、Xalan、Apache FOP和PDF-SAM。此外还有官方的XSLT样式表分发,以及我自己的XSLT自定义。)
DocBook不是一个交钥匙解决方案。如果不阅读手册,你将无法快速行动。如果您对XSLT一无所知,就必须学习。
另一方面,对于编写文档,您真正需要知道的XML标记只有十几个或两个。(真正的专业知识在从XML源代码生成文档的过程中发挥作用。)如果团队中有一个人愿意负责编写文档构建脚本,那么团队中的其他人都可以学习DTD,并做出出色的贡献。
无论如何。。。DocBook肯定有一些缺点。对于技术作者来说,这不是最简单的系统。但这是我所知道的最好的开源工具。
"Subversion Book"是用DocBook编写的。这里有一个页面,链接到不同的书籍版本(单个html、分块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
关于弹药,有一位值得信赖的老实用主义程序员,第14章:纯文本的力量。
作为务实的程序员,我们的基础材料不是木头或铁,而是知识我们将需求收集为知识,然后表达我们设计中的知识,实现、测试和文档。我们相信持久地存储知识是纯文本。通过纯文本,我们给出我们自己操纵的能力手动和以编程方式,虚拟使用我们可以使用的每一种工具。
我们使用wiki(特别是Trac提供的wiki)的原因有两个。此外,如果我们真的需要,我们可以获得标记的文本版本,并在纯文本环境中对其进行操作(例如,在提交期间作为svn注释的一部分)。
一种可以很容易地简化为纯文本(非二进制)的格式绝对是必须的。对我们来说,能够将上转换为像PDF这样的漂亮格式并不是很重要。
Word具有文档更改跟踪功能(尽管只有在您接受更改之前才能运行),您还可以对文档进行grep(文本未加密)。所以我不确定你的任何一个论点是否经得起推敲。我很想给你改变现状的弹药,但随着年龄的增长,我变得厌倦和愤世嫉俗。
我们在文档中使用MS Word(这比以前的选择(Lotus WordPro-ugh!)有了很大的改进)。
我们使用一个wiki,特别是Atlassian的Confluence。
这是一个商业产品,非常棒。我们选择它而不是免费/开放的wiki引擎的原因之一是,它有一个全面的所见即所得编辑器和各种其他功能,使熟悉Word的用户更容易访问它。
我们还想出了一个巧妙的技巧,将图像、设计、线框等存储在Subversion中,然后通过Apache/SVN网络接口模块在wiki文档中嵌入指向这些资源URL的链接;如果你感兴趣的话,这里有关于我们如何做到这一点的说明。
与Dylan的组织一样,我们也使用出色的Confluence wiki。我写了一篇文章,解释为什么这种更好的方法叫做Wiki是我的文字处理器,它应该给你一些改变这种情况的理由。
将wiki用于内部文档的好处包括以下几点。
- 无论你的模板多么好,文字处理用户都会被改变布局和排版所吸引,这会浪费时间,降低一致性
- wiki提供了全文搜索,这是不可能对所有人编写的MS Word文档进行的
- wiki提供文档版本历史记录;我从来没有听说过一个团队成功地将所有修订保存在Word文档中,并始终能够比较旧版本,或者使用版本控制系统(SharePoint可能除外,但这是完全不同的失败情况)
- wiki使文档之间的超链接变得容易;在Word文档集合中,很难在文档之间建立可靠的链接,因此新文档最终会将旧内容复制到新的整体文档中,这意味着它们需要更多的时间来阅读和书写
- 不同的人可以同时编辑单独的wiki页面,当多人同时编辑同一页面时,Confluence可以合并更改;对于一次只能由一个人编辑的Word文档,协作更加困难
- 类似wiki的Confluence会根据wiki结构和标签自动生成导航页面;你需要一个图书管理员和大量的纪律,才能浏览大量的Word文档
- wiki页面的加载和显示速度通常比Word文档更快
- wiki页面有更多的自动元数据;您需要模板和规程来确保Word文档在文档属性中始终设置有"标题"、"作者"one_answers"版本",并且在屏幕上和打印中的文档中可见
如果你想要更多的弹药,那么Atlassian博客上有很多维基推广。
您可以要求文档采用OOXML(在Word的情况下为.docx
)格式。然而,在我看来,它并不像使用ODT那么理想,它仍然只是一个zip文件,里面有一堆XML文件。:-)
文本格式有助于将文档与生成的项目(如JavaDoc、API引用或数据字典)合并。它的伸缩性也比word好得多,word很难用于大型文档。最后,允许include的格式允许多个作者同时处理一个文档。
LaTeX和FrameMaker(我曾使用过这两个系统)都具有非常优越的索引和交叉引用功能,并且都具有本地文本格式或可以包含的本地格式的文本版本(FrameMaker中为MIF)。它们也都比文字稳定得多。
我构建了一些工具,可以读取数据字典并生成文档,这些文档可以通过稳定的索引和双向交叉引用包含在更大的文档中
整个开发团队是反对这个要求,还是一个小组?如果是整个团队,只需忽略授权并使用基于文本的格式——这不会是员工第一次忽视愚蠢的规则。如果你过去没有对此大惊小怪,效果尤其好。如果您有,管理层可能会特别仔细地查看您的文档。
MS Word支持文档更改跟踪和同行评审。
新的MS Office格式完全基于XML(要查看此信息,请将MS Word.docx文件重命名为.zip,然后解压缩以查看)。
也许Office2007既符合贵公司的要求,又符合您的担忧?
您至少可以比较Word文档,查看"额外"菜单中的"跟踪更改"命令,或者使用DeltaView等软件。通过lifehacker.com上的谷歌搜索第一链接找到。谷歌桌面搜索或其他类似程序应该可以搜索word文档,这些程序可以索引他们能够读取的所有文件。
他们坚持让你用Word写还是只用Word格式?你可以用文本格式书写,然后自动将其转换为Word。
是否将文档文件存储在某种版本控制系统中,最好与源代码一起存储?我建议这样做(这样可以很容易地获得旧软件版本的文档)。
如果您确实将文档存储在VCS中,您会注意到纯文本或基于XML的文件对此要好得多,因为您可以获得diff;此外,文本文件之间的更改通常比二进制文件之间的变化更有效地存储。
这里不是为了保护MS产品,但MS word可以区分文档。
如果您使用Beyond Compare作为源代码管理系统的差异工具(就像我们使用Perforce一样),它将显示Word文档修订版之间的差异。诚然,它只显示了文本差异——没有显示格式的更改——但这通常足以让你看到发生了什么变化。
这只是投资Beyond Compare的另一个原因,因为它是我使用过的最精致的软件之一,也是我在软件上花费的最好的30美元(如果你买了几个就少了)
有很多用于word文档比较的工具。我目前使用的是一个python脚本,它在word的内置比较和合并功能上添加了一个命令行。
http://nicolas.lehuen.com/index.php/post/2005/06/30/60-comparing-microsoft-word-documents-stored-in-a-subversion-repository
自动将word文档中的所有文本提取到文本文件中应该很容易。因此,您可以编写一个脚本,从word文档创建文本文件,并进行grep、比较、版本控制、查看这些文本文件。
当然,这不是一个理想的解决方案,因为你的格式很松散,但它应该可以工作。
我认为有一些程序可以将Word文档转换为纯文本。使用其中一个将单词doc转换为纯文本,然后使用diff、grep等
还可以查看DocBook的推荐工具链。