How to best version design documents? [closed]

Question

There has been some discussion on SO (here and here) before on how office documents can be versioned, however I think my question is still a little different.

My programming projects start with a project folder that is empty except for a subfolder named "Design Documents", which contains a draft of the project's functional spec to begin with and is later expanded to contain API specs or whatever else is needed.

Naturally, I check these files into SVN as well. What I'm looking for is good file formats and strategies to play well with the whole versioning, diff'ing and merging processes. For example, I reckon it would be best to store word processor files as XML, or would the diffs be ugly and useless for human readers? Here's what I'd like to do:

• diff and merge text documents (must-have OOo, nice-to-have MS Word)
• diff (and maybe merge, though that might turn out to be conceptually difficult) schema drawings, like UML diagrams. I was thinking that these could be independent XML/SVG files and be linked into the text documents, but I don't know enough about how these documents work to tell if that's actually possible.
• show automatically updated revision numbers inside the text documents (maybe with svn:keywords)

Has anybody done this kind of thing already? There's probably a number of documentation and tutorials on OOo files etc. that I could look up, but while I also appreciate pointers to those, I'm mainly looking for first-hand accounts of things that did or didn't work in practice.

---

Edit: Just to be sure, there's no "non-technical users" involved here. It's just programmers and the documents are for use on programming projects only. There may be PDFs to be published but that's going to be just another build artefact, nothing that has to be versioned.

Still, we don't really want to use Tex or the like. I know it's great and all, but I just can't be bothered for a simple text document. We'd have to learn it, get all the extra packages right, add Tex-to-PDF rendering to our build process etc. It would be like a little programming project just for the two or three docs. If anything, I'd rather use HTML, but a word processor still seems like a good option to me, except that I want good versioning.

There's another thought: Is there something like an SVN plugin for OOo or the other way around? Or even, what would it take to add SVN support to OOo? Like a "Synchronize" option in the File menu and a "Revision number" text field. I mean, that would not really be part of our business, but it would be cool, and after all, I'm the boss.

Answer 1

WYSIWYG editors (Word, OpenOffice) generally don't see a reason why anybody else should mess with their files, so finding an editor which a non-technical user can use and which is friendly to a version control system is impossible. Exception: git has a filter which can look into OpenOffice files. I'm not sure if you can use keyword expansion, though.

I suggest to use a wiki and a week of training for your users how to use it. It solves all your problems (some wikis can even be checked into a version control system). As I said in a different post, the sole obstacle is that users will take a few days to get accustomed to the idea. After that, they will love it.