How to best version design documents? [closed]

Question

Closed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 2 years ago.

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

As Aaorn Digulla noted, a wiki is a great idea. You have to realize that the only way you are really going to achieve what you want is to rethink your entire document strategy.

No software is going to fix the issue of incompatible file formats and not being able to compare different versions. The tools you are using now are the wrong tools for the job. It's going to be tough, uncomfortable, and possibly expensive to change your toolset and your way of thinking, but that's the cost of being able to achieve what you want, which will end up paying for itself 10 fold.

Just think back to the difficulties you had initially with schema docs, UML diagrams, and even something as simple as planning out a Word document. Those worked up until this point and they got you this far, but the only real way forward is to move on to tools that were designed for what you need now.

Note: the ultimate solution might not be a wiki, but it's definitely not what you are using now, either. You need to explore a bit and try a few things out.