Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question

6 Answers 6

up vote 4 down vote accepted

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, can can always get two versions and use the feature of the authoring system to diff them.

share|improve this answer
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 '11 at 9:41
    
That's not the only problem, locking and overwriting changes is a problem when there are multiple editors –  NickC Mar 2 '11 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. –  Loki Astari Mar 2 '11 at 19:27
    
This answer seems more like a comment about some other answer. For example, the question mentions nothing about blobs. –  Bryan Oakley Mar 30 '12 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.

share|improve this answer
2  
If nothing else it's amusing to see what v1.0 of the specs looked like , compared to what ships! –  Martin Beckett Mar 3 '11 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.

share|improve this answer
    
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) –  Edison Chuang Mar 2 '11 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. –  Mike Brown Mar 2 '11 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. –  Bryan Oakley Mar 30 '12 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.

share|improve this answer

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.

share|improve this answer
    
It doesn't adress the "Overwriting changes from multiple editors" issue though. –  Omar Kohl Mar 3 '11 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?

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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