How to keep code and specs in sync? - are there good tools [closed]

Question

In my team we've got a great source control system and we have great specs. The problem I'd like to solve is how to keep the specs up-to-date with the code. Over time the specs tend to age and become out of date

The folks making the specs tend to dislike source control and the programmers tend to dislike sharepoint.

I'd love to hear what solutions others use? is there a happy middle somewhere?

Answer 1

Nope. There's no happy middle. They have different audiences and different purposes.

Here's what I've learned as an architect and spec writer: Specifications have little long-term value. Get over it.

The specs, while nice to get programming started, lose their value over time no matter what you do. The audience for the specification is a programmer who doesn't have much insight. Those programmers morph into deeply knowledgeable programmers who no longer need the specs.

Parts of the specification -- overviews in particular -- may have some long-term value.

If the rest of the spec had value, the programmers would keep them up to date.

What works well is to use comments embedded in the code and a tool to extract those comments and produce the current live documentation. Java does this with javadoc. Python does this with epydoc or Sphinx. C (and C++) use Doxygen. There are a lot of choices: http://en.wikipedia.org/wiki/Comparison_of_documentation_generators

The overviews should be taken out of the original specs and placed into the code.

A final document should be extracted. This document can replace the specifications by using the spec overviews and the code details.

When major overhauls are required, there will be new specifications. There may be a need to revisions to existing specifications. The jumping-off point is the auto-generated specification documents. The spec. authors can start with those and add/change/delete to their heart's content.