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?
I think a non-Sharepoint wiki is good for keeping documentation up to date. Most non-technical people can understand how to use a wiki, and most programmers will be more than happy to use a good wiki. The wiki and documentation control systems in Sharepoint are clunky and frustrating to use, in my opinion.
Mediawiki is a good choice.
I really like wikis because they are by far the lowest pain to adopt and keep up. They give you automatic version control, and are usually very intuitive for everyone to use. A lot of companies will want to use Word, Excel, or other types of docs for this, but getting everything online and accessible from a common interface is key.
I don't know of any particularly good solution for precisely what you're describing; generally, the only solutions that I've seen that really keep this sort of stuff in sync are tools that generate documentation from the source code (doxygen, Javadoc).
One technique used to keep the documentation in sync with the code is literate programming. This keeps the code and the documentation in the same file and uses a preprocessor to generate the compilable code from the documentation. As far as I know this is one of the techniques Donald Knuth uses - and he's happy to pay people money if they find bugs in his code.
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.
As much as possible the spec should be executable, via rspec, or doctest and similar frameworks. The spec of the code should be documented with unit tests and code that has well named methods and variables.
Then the spec documentation (preferably in a wiki) should give you the higher level overview of things - and that won't change much or get out of sync quickly.
Such an approach will certainly keep the spec and the code in sync and the tests will fail when they get out of sync.
That being said, on many projects the above is kind of pie-in-the-sky. In that case, S. Lott is right, get over it. They don't stay in sync. Look to the spec as the roadmap the developers were given, not a document of what they did.
If having a current spec is very important, then there should be specific time on the project allocated to write (or re-write) the spec after the code is written. Then it will be accurate (Until the code changes).
An alternative to all of this is to keep the spec and the code under source control and have check-ins reviewed to ensure that the spec changed along with the code. It will slow down the development process, but if it is really that important ...