views:

238

answers:

6

Hi,

Is there any software that manages specification documents? (high level and low level documentation).

Something that helps you organize specification titles/numbering, and you can quickly access a document while viewing the table of contents etc.

Versioning would also be great!

A: 

Have a look at OnTime. A single user license is free.

Doug L.
A: 

If you have a Windows server, you could try installing Windows SharePoint Services.
There is no extra licence cost, either server or client.

More info: http://office.microsoft.com/en-us/sharepointtechnology/default.aspx
Download links: http://technet.microsoft.com/en-us/windowsserver/sharepoint/bb400747.aspx

Nico
+1  A: 

You could consider checking it into a separate area of your source control. It would give you free revision tracking and keep it close to the developers who are going to be working with it. It does not come with several of the features you asked for but is still very workable. Another good point is that it is free ;).

smaclell
The documentation belong in source control, right along side your code, and scripts.
EvilTeach
A: 

Microsoft Word, or Open Office can generate section numbering. For Word, modify the style named "Heading 1" and click on "Format Numbering". Do this with the other "Heading" sections.

You can also use a field to generate a table of contents which will link to the sections of the document.

Matt Brunell
A: 

I guess a wiki (e.g. twiki) would work, if you are okay with the fact that anyone can edit the documents by default.

André
+1  A: 

I've had success with LaTeX and FrameMaker. Both of these systems allow you to write and maintain large, complex technical documents such as specifications. Once you get beyond 100-200 pages word becomes unwieldy. Both FrameMaker and LaTeX have the following key advantages over word or other systems:

  • From the ground up they are designed to split a document over multiple files. This means that different people can work on the document at the same time. In both of these packages this facility is mature and robust - i.e. it works well.

  • You can check the documents into source control (although you can do this with pretty much anything).

  • They can support consistent styles applied across the whole document or a collection of documents

  • They can single-source documents to multiple media - Framemaker can do PDF, print, HTML and chm from the same source.

  • They can manage large documents. Framemaker is quite widely used in Aerospace circles where documents can run to tens of thousands of pages.

  • Their indexing and cross-referencing functionality is vastly superior to that in Word.

  • You can build multi-volume documents with a common index and cross-referencing across the volumes.

  • You can generate parts of the documentation such as data dictionaries or API documentation and index and cross-reference in and out of the generated documentation with stable anchors. For example, you can get a Doclet that generates MIF files that works with JavaDoc. I've done several different approaches for database schema documentation, including data dictionary tooling for This product that generates files to import into a larger document. This allows generated documentation of this sort to be seamlessly integrated into a wider spec document.

  • The tools do not regularly mangle the files in the way that word does.

  • Unlike a wiki or any solution based on Sharepoint, the reader of the documentation does not need to be connected to a live server.

  • You can have conditional parts to the documents, so you can single-source multiple versions of the document without having to maintain several copies of the document.

  • On a larger scale, these systems allow a single spec document, even holding a log of change requests if desired (see the entry on conditional text above). Over time, this mitigates the issue of 'specs spread across 200 assorted word documents and spreadsheets with no clear point of reference to tell what is releant or current.'

Framemaker is not free, but has a shallower learning curve than LaTeX. If you can get the capex, I'd recommend it unless you are familiar with LaTeX already. It's also less of a culture shock for people who are used to word.

ConcernedOfTunbridgeWells