Today, One of my colleague and I have a debate about "Should we put the specification documents in source control system such as SVN?". In my opinion, It should be. Everything relate to developing project should be controled carefully with source control system. Is it a wrong concept in software development process?

6 Answers 6


So what if most source control systems only store them as blobs? Most people don't give a rip about the diffs between docs, but if you do, you can always get two versions and use the feature of the authoring system to diff them.

  • 2
    True, I'm happy if SVN just makes sure I always have the current version. Diffs are less important most of the time.
    – Zachary K
    Mar 2, 2011 at 9:41
  • That's not the only problem, locking and overwriting changes is a problem when there are multiple editors
    – Nicole
    Mar 2, 2011 at 18:58
  • 1
    Diffing documents is not important to you. But to a PM the ability to see changes in the specs is very important. Mar 2, 2011 at 19:27
  • This answer seems more like a comment about some other answer. For example, the question mentions nothing about blobs. Mar 30, 2012 at 23:18

With hard disk space at pennies per gigabyte per month, there's no good reason not to put documents in the source control system, and it is likely to be useful. My personal preference is to write documents using inline markup, e.g. Wiki Markup or DocBook. This allows use of powerful tools for document comparison and revision.

  • 3
    If nothing else it's amusing to see what v1.0 of the specs looked like , compared to what ships! Mar 3, 2011 at 0:27

Versioning specification documents is definitely a worthy goal.

However, are your specification documents text-only and in a plain text file? If so, this may be a good solution.

If not, source control is probably not the right place for them — source control is bad for binary files.

Usually, plain text files are neither as good for formatting or for quick viewing, so a wiki with versioning is probably a better idea.

  • Usually, Our document includes not only plain text content but also picture such as UML diagram or something like that. I totally agree that binary-formated files are not suitable for source control system. However, I think it is better than nothing. right? If there were wiki we can adopt. That would be great. But I worry about that. Our people would be "too busy" to learn how to use wiki.(sad) Mar 2, 2011 at 6:24
  • 1
    There are many wikis now-a-days with WYSIWYG editors. I'm a very reluctant sharepoint convert. As a developer, I hated sharepoint with a passion. Then I signed up with Microsoft BPOS which comes with sharepoint and used it for collaborating on projects with remote team members. It has wiki, forums, calendars, and document libraries (which does tracking for Microsoft Office Docs) and a bunch of other stuff that just makes project collaboration dead easy. I think a Wiki as a living specification is perfect because of the history that it provides. Mar 2, 2011 at 6:33
  • Strictly speaking, source control is not bad for binary files. It's not like it destroys or mutates them in some way. Arguably, however, binary files are bad for source control, but only because they take up lots of disk space and make cloning slower. Disk space is cheap, though, so it's not as bad as it was even 5years ago. Mar 30, 2012 at 23:19

All the documents should be in some form of archive (preferably with revision controls).

Source control systems is one solution. But usually these systems are designed for plain text documents. Thus things like Word or RTF documents etc do not fit so nicely (especially when you try and compare different version).

But There are other solutions specifically designed for documents. SharePoint springs to mind, but I am sure there are others.


Definitely. The problem that documents are stored as binaries (for example word documents) is annoying. A nice workaround is if you use one of the Tortoise tools (I have tried SVN and Mercurial) you can choose "Visual Diff" that allows you to choose docdiff. With docdiff you get to see all the changes with colours and stuff :-). The main disadvantage is that every time you make a change the whole document is commited again (not just the change). But considering that text documents aren't huge normally and that space probably isn't your main issue this is no problem.

I'm sure you can use docdiff without Tortoise, it's just that I haven't tried it.

  • It doesn't adress the "Overwriting changes from multiple editors" issue though.
    – Omar Kohl
    Mar 3, 2011 at 0:23

There is an alternative approach that you should discuss: BDD

Please consider Behavior Driven Development with executable specifications. Your specifications get simplified into a series of Given - When - Then sets of statements that are stored in text files. A BDD tool such as Cucumber or SpecFlow converts those text files into executable tests, that your build tool can execute.

Cucumber: http://cukes.info/ - BDD for Ruby

SpecFlow: http://www.specflow.org/ - BDD for .Net

For a quick demo of workflow with a tool like SpecFlow, checkout Rob Conery's SpecFlow walk-through: http://tekpub.com/view/concepts/5

Now, not only are you versioning your code, but your specifications, and your Continuous Integration tool (think TeamCity, CruiseControl, Hudson, etc) is enforcing that all specifications are still valid on EVERY build... Is that valuable to you?

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.