您使用什么工具/格式来编写规范？

Question

我想知道您用什么样的工具来编写规范。我认为使用支持某种纯文本格式的工具是至关重要的，这样就可以使用像SVN这样的源控制系统来控制规范。对于代码的规范，重要的是要有所有更改的历史记录。

目前我们以XML格式编写规范。 TeX也是一种替代方案，但对于那些从未使用过它的人来说很难。

请告诉我，您使用哪种工具或格式进行规范。

Answer 1

使用XXE编辑的DocBook，需要发送给客户时，使用xslt翻译为pdf。

有史以来最好的改变，更容易编写，更容易合并，当它被转换时，它看起来并不像MSWord那样非常不专业。

另外，结构化文档样式已经存在，不像血腥的单词，你必须与之斗争才能开始工作。

Answer 2

我们使用了TeX（MikTeX），它很完美，因为：

• plaint text - 在Vim / Notepad中编辑 - 随处可见
• 使用预定义宏的强大格式化我们其中一个人
• onclick generation to PDF

唯一的问题是获取图表（来自ArgoUML）。

在另一个项目中我看到了使用Word模板 - 从上面指示的可怕内容。

我考虑在内联网上使用类似wiki / forum的东西。想象一下使用GoogleDocs - 有版本，它在线..但不适用于商业开发。

Answer 3

在工作中，我们的许多文档都在Sharepoint或其他文档系统下，这些文档系统真正减慢了文档的“发布”速度。这意味着整个地方都有文件的副本，让某人正确地释放某些东西是一件令人头疼的事。由于这个原因，我通常会收到电源点或废纸的规格。所以我在工作中提出了一个wiki（Media Wiki），我们现在保留所有项目规范。这使得它们可以被公司中的任何人查看并由我们的开发组编辑。有时候开发人员会在他们经过或者其他事情时要求老板澄清，开发人员可以自己更新规范，我认为这是一个巨大的优势。此外，当人们使用历史记录更新包含新信息的规范时，很容易看出最近的变化是什么 - 这意味着我可以看到之前发生的事情以及现在需要发生的事情，我认为这是一个巨大的优势。

我仍然保留一些在我墙上的笔记本纸上乱涂乱画的规格作为提醒。

Answer 4

我开始使用Docbook来做所有这些事情。它简单，灵活，并将生成html，tex（以及pdf）等。

Answer 5

Microsoft Word。我知道它不符合您的要求，但在我所有的工作中，我已经使用Microsoft Word作为规范。您可以，而且我已经将Word文档放在源代码管理系统中 - 您唯一丢失的是能够在文档之间进行区分。虽然我依旧记得在某处读到有可以使用的差异工具。

Answer 6

在工作中我们使用维基，因为它们非常适合协作，但Microsoft Word可以正常工作。

您实际上可以使用Word本身来区分Word文档的两个不同版本 - 它使用“轨道更改”功能来显示差异。 （如果你不相信我，请尝试使用TortoiseSVN来扩展两个版本的Word文档。）

对于长文档，我实际上更喜欢使用Word而不是wiki，因为它非常适合编辑长文档，而且业务人员更适合使用Word文档。