What tool/format do you use for writing your specifications?

Question

I would like to know what kind of tool you use for writing your specifications. I think it's essential to use a tool that supports some kind of plain text format so that one can control the specification with a source control system like SVN. For the specification as for the code as well, it's important to have a history of all changes.

At present we write our specification in a XML format. TeX would also be an alternative, but it's hard for people who have never been working with it.

So let me know, what kind of tools or formats you use for specifications.

Answer 1

I've come to use Docbook for all such things. It's easy, flexible, and will generate html, tex (and thus pdf), etc.

Answer 2

We used TeX (MikTeX) and it was perfect because:

• plaint text - edit in Vim/Notepad - just everywhere
• powerful formatting using predefined macros one of us did
• onclick generation to PDF

The only problem was to get diagrams (from ArgoUML) in.

At another project I saw using Word templates - awful stuff directed from above.

I'd consider using something like wiki/forum on intranet. Imagine using GoogleDocs - there is versioning, it's online.. but not applicable for commercial development.

Answer 3

Microsoft Word. I know it doesn't meet with your requirements but in every job I've had I've used Microsoft Word for the specifications. You can, and I have, put Word documents in a source control system - The only thing you lose is the ability to diff between documents. Although I do vaguely remember reading somewhere that there are diff tools for word that can be used.

Answer 4

DocBook edited with XXE, translated to pdf with xslt when needed to be sent to clients.

Best change ever, so much easier to write, so much easier to merge, and when it's converted it doesn't look so godawfully unprofessional as MSWord.

Plus the structured document style is already there, unlike bloody word which you have to fight with to get working.

Answer 5

At work a lot of our documents go under Sharepoint or some other document system that really slows down the "release" of a document. This means there are copies of the documents all over the place and getting someone to properly release something is a headache. Due to this I normally received specs in power point or scrap paper. So I put up a wiki (Media Wiki) at work that we now keep all project specs in. This allows them to be viewable by anyone in the company and editable by our development group. Sometimes a developer will ask the boss for a clarification as they pass by or whatever and the developer can update the spec themselves which I think is a huge advantage. Also, when people update a spec with new information using the history it is very easy to see what the most recent changes were - meaning I can see what was happening before and what needs to happen now, which I think is a huge advantage.

I still keep a spec that was scribbled on some notebook paper up on my wall as a reminder.

Answer 6

At work we use a wiki because they are great for collaboration, but Microsoft Word will work.

You can actually diff two different versions of a Word document using Word itself - it uses the "track changes" feature to show the differences. (If you don't believe me, try diffing two versions of a Word document using TortoiseSVN.)

For long documents, I actually prefer Word over the wiki because it is well suited to editing long documents and business folks are more comfortable working with Word documents.