I know you can use source control software for source code, but can you use it for your technical documents as well? For example, can you store a Word document and it keep a history of changes (I know it has track changes, it's just and example)? Thank you.
+1
A:
MS Word documents are pretty much treated as binary files, and so it's pretty much impossible to diff or merge different versions of a Word file.
That doesn't mean it can't, or shouldn't, be put under version control, just that it won't help you much in resolving conflicts.
If you want that, you may want to store your documents in a plaintext format (such as .tex)
jalf
2009-05-02 22:30:22
Well, most source control systems allow you to specify a special diff program for a filetype, so you could use your wordprocessor as the diff tool (most allow that, at least OO.org and MS Word). Merging might be harder though, so you should probably set them as "not mergeable".
sleske
2009-05-02 22:52:47
@sleske, choosing a diff tool will only affect how the tool *present* differences to the user. It won't help the VCS tool to figure out what's changed (unless it has specific merging support for your specific binary file type) when merging; all conflicts will just be thrown in the face of the user.
bignose
2009-05-02 23:09:20
@bignoseYes, just what I wrote :-). "you should probably set them as 'not mergeable' ". Some VCS (e.g. Subversion) let you specify custom merge programs. If you really need it, you could write a custom merge program for MS Word etc., then you could actually merge these files. Hence the "probably" above ;-).
sleske
2009-05-03 17:13:07
A:
Sure. We do this at work and really helps keep track of the tech docs, which sometimes can change as frequently as the source code itself :)
danvin
2009-05-02 22:30:51
what format do you use for the tech files? word, notepad, something else?
johnny
2009-05-04 14:25:04
+2
A:
Yes.
However, note that many documents will be stored as binaries. This will limit the utility of storing them in source control, making it harder to see fine-grained changes.
If you have LaTeX documents or XML-based documents then things work even better.
Naaff
2009-05-02 22:30:54
A:
Yes you can. You can upload files to your version control and keep an history of change for them.
Alberto Zaccagni
2009-05-02 22:31:34
+4
A:
If you are on a Windows platform, then TortoiseSVN has some really useful features that will let you diff (but unfortunately not merge) Word documents. It interacts with an installed Word directly, and when you request a diff it runs a script that loads both documents to compare into Word and uses Word's built-in document compare to compare them.
With that feature, combined with Subversion's locking (where editors must request a lock on a document to turn off the read-only flag), I have found it very easy to manage Word documents with Subversion. It's not quite as convenient as plain text, but when you must produce Word documents it's certainly doable.
Having said the above, in general terms documents are a product of the software development process and must be version controlled in some way. Otherwise, your process is incomplete.
Greg Hewgill
2009-05-02 22:38:17
+1
A:
In theory you can source control anything, I've heard about designers source controlling their Photoshop files. If you always write clear commit messages, it's easy to roll back to a previous version.
Wolfr
2009-05-02 22:44:59
+3
A:
Version control systems, while they can store arbitrary files like Word documents, are much more effective on text documents edited as source by the user, because the differences can be represented in a line-oriented fashion meaningfully to the user.
For this and many other reasons, I write all my documentation these days in reStructuredText source files, edited along with other source files and tracked in version control. The HTML and PDF versions are rendered along with the rest of the project's generated files at build time.
bignose
2009-05-02 22:56:26
A:
As everybody else said, you can definitely use source control for your technical documentation. But, I'm definitely going to come down on the side of the poster who suggested restructured test. The whole point of revision control is to be able to see diffs and merge amongst them, and in my book, you're going to need to be using text files to do it.
Some other options aside from restuctureText are DocBook and DITA. They're pretty popular in the technical publishing world and both are based on XML, so there are some decent support tools for them. For DocBook, you might check out XML Mind.
easel
2009-05-03 04:49:53
A:
In fact, the MS collaboration solution - namely, Team System - uses SharePoint to achieve just this. I know almost nothing of SharePoint, and have been easily using it to keep versions of technical word docs for a while now.
If you want to use it directly from within word, you can try the word add-in available here.
Assuming you use Visual Studio as the primary interface for team system services, click View->Team Explorer. If you haven't already, set up your repository server and add your project (there are nice online video tutorials for most of this stuff).
Under your project tree node, go to Documents, and create/add your doc. Edit it, check in & check out at will (and let your teammates do the same). When you need a version history of the doc, open it from the team explorer window. In the word app that would launch, you should have (by default) at the right a 'SharePoint' panel. (I'm writing this without access to a team client, but I'm pretty sure I'm not making any un-recoverable mistakes..). In it, navigate to the info tab, and scroll down to 'History...' (or is it Versions...? exact details tomorrow.)
Ofek Shilon
2009-05-03 19:18:36