公司坚持使用二进制格式的所有文档 [英] Company insists on using a binary format for all our documentation
问题描述
- 将文档的版本相互对准（所以同行评审是一种痛苦 - 因为我们工作的域名，所有更改的同行评审是必不可少的）
- 填写一个文件夹 - 填满关键字的文档
你用什么来写文档，为什么？
还请给我弹药来改变这种情况...
我最近开始使用DocBook XML来撰写我的文档。
上面是一种纯文本格式。您可以将大型文档分解成多个文件，并使用节点将它们全部合并到一本书中。自动生成目录和索引。文档内链接（在任意文本中，指向章节或部分）非常容易。并且按一个按钮，我可以创建一个单一html文件版本，一个chunked-html版本（每章一个文件）和一个PDF版本。
经过一些调整和定制，我对输出非常满意。文档看起来很好 !!
DocBook被真正的发行商广泛使用（最引人注目的是O'Reilly），它已经在更多十五年以上，所以达到一定程度的成熟度。
另一方面，所有的处理都是使用XSLT完成的，使用工具的特别收集。 （我自己的docbook管道包括Python，Java，Xerces，Xalan，Apache FOP和PDF-SAM。加上官方的XSLT样式表分发，以及我自己的XSLT自定义。）
DocBook不是一个交钥匙的解决方案。没有阅读手册，您将无法快速前进。如果您不了解XSLT的任何内容，您将不得不学习。
另一方面，您只有十二个或两个XML标签需要知道要写的文件。 （真正的专业技能在XML源代码生成文档时发挥作用。）如果您的团队中的一个人愿意负责编写文档构建脚本，那么团队中的所有其他人都可以学习DTD并做一个体面的工作贡献。
无论如何... DocBook肯定有一些错误。这不是最简单的技术创作系统。但是这是我知道的最好的开源工具。
Subversion Book是用DocBook编写的。这是一个包含不同图书版本（单页，chunked-html和PDF）链接的页面：
这里有一个链接到DocBook XML源代码第一章，以便您可以了解它的工作原理：
I work at a company that, for some reason, insists that all our development documentation should be in MS Word format. Which, being a binary format, means we cannot:
- Diff versions of a document against each other (so peer reviewing them is a pain - because of the domain we work in, peer reviews for all changes are essential)
- Grep a folder-full of documents for keywords
What do you use to write documentation in and why?
Please also give me ammo to change this situation with...
I recently started using DocBook XML to author my documentation.
On the upside, it's a pure text format. You can break a large document into multiple files, and use nodes to bring them all together into a single book. Table of contents and index are automatically generated. Intra-document links (within arbitrary text, pointing to chapters or sections) are very easy. And with a push of a button, I can create a single-html-file version, a chunked-html version (one file per chapter), and a PDF version.
After some tweaking and customization, I'm very happy with the output. The documents look great!!
DocBook is used extensively by real publishers (most notably, O'Reilly), and it's been around for more than fifteen years, so it's reached a certain level of maturity.
On the other hand, all of the processing is done with XSLT, using an ad-hoc collection of tools. (My own docbook pipeline includes Python, Java, Xerces, Xalan, Apache FOP, and PDF-SAM. Plus the official XSLT stylesheet distribution, and my own XSLT customizations.)
DocBook is not a turnkey solution. You won't be able to get going quickly, without reading the manual. And if you don't know anything about XSLT, you'll have to learn.
On the other hand, there are only a dozen or two XML tags that you really need to know to write the documents. (The real expertise comes into play during doc generation from the XML sources.) If one person on your team was willing to be responsible for writing the doc build script, then everyone else on the team could just learn the DTD and do a decent job contributing.
Anyhow... DocBook definitely has some faults. It's not the easiest system for tech authorship. But it's the best open source tool I know of.
The "Subversion Book" is written in DocBook. Here's a page with links to the different book versions (single-html, chunked-html, and PDF):
And here's a link to the DocBook XML sources for the first chapter, so that you can get an idea for how it works:
http://sourceforge.net/p/svnbook/source/HEAD/tree/branches/1.7/en/book/ch01-fundamental-concepts.xml
这篇关于公司坚持使用二进制格式的所有文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
