Document Management and Version Control?

Tom wonders: "I am working in a medium-sized software development company. The functional analysts use Microsoft Word to document the specifications, and Sharepoint to publish the documents. However we'd like to improve our process to have better revision control and traceability. We have looked at alternatives like using Wikis, or static HTML documents with CVS. The functional analysts want ease of use, while we developers would like to see high-quality end products, revision control (i.e. tagging & branching of the document base), and traceability features. What tools and document formats do you use and would recommend?"

Comments

Baby step #1: source control + existing docs

[dsandler]

It's pretty shocking to change everything (document format, writing environment, collaboration tools) all at once. Start with reasonable source control, the best bacon-saving device you can get. Have everyone check existing docs (Word, HTML, whatever) into source control; Even though diffs are meaningless for the binary formats, the other benefits (versioning, collaboration, remote storage, tags, platform independence) are huge. It's the quickest way to put an end to the madness of emailed .doc files and accidental deletions.

If you've got a lot of Windows users, go with Subversion and get everyone to install the TortoiseSVN shell extension, which offers the most natural GUI for new (and experienced!) users of version control.

Once everyone's comfortable with SVN, you can then start migrating to text-based document formats in which the source control diffs mean something (LaTeX, XML, reStructured, etc.)

Re:ODF + SVN: auto unzip and rezip?

[Noksagt]

ODF files are just zip files which contain the content in an XML file with supporting text and binary files. The text files are auto-generated & so may have "weird diffs" particularly when multiple people/programs/platforms work on them. I have an ical server backed by subversion's webdav & the diffs are always very amusing, as each program changes whitespace & other such nonsense.

The diffs might still be more usable than those for a 100% binary (zipped) file, particularly for single-user situations.

Has anyone played with compressing/decompressing ODFs for use with version control software? Any pointers?

Depends very much on your analysts

[Circuit Breaker]

Where I work, developers use CVS exclusively. It has its quirks, and we've considered alternatives, but the combination of CVS+TortoiseCVS+Jalindi Igloo (Visual Studio integration)+Jira is unbelievebly hard to beat (Subversion doesn't have a reasonable SCC connector, and nothing else has anything that comes close to TortoiseCVS -- even TortoiseSVN is clunky and awkward by comparison. Oh, and CVS mergepoints work perfectly, unlike the nonexistent merge tracking capabilities of Subversion).

When our "functional analysts alike" guys wanted version control, we naturally gave them the tried-and-tested CVS, and gave them instruction on its use. It was a horrible failure. The update-edit-change-commit cycle which is so trivial to developers just didn't work. The people are not dumb - just have a different mindset. We had also tried a Wiki (MoinMoin, works well for devs), but its inability to search or version Excel files make it irrelevant.

Eventually, much to my dismay, we settled on Sharepoint. And while it's clunky, horrible, keeps only the 7 latest versions of any file, has no branching and is often inconsistent with error messages, them users are able to work with it without requiring assistance.

Do not confuse a feature list with applicability of a tool to the situation at hand which, it appears, might depend more on the people involved than anything else.

Svnwiki, of course

[Azul]

I would suggest using svnwiki, a wiki system that stores its whole contents in a Subversion repository (Disclaimer: I am the main author of svnwiki). That allows you to use the usual svn commands (svn diff, svn log, svn update, etc.) to work with your wiki as well as using the web interface.

You can see an example wiki (in spanish) and its associated svn repository (login as anonymous, password is the empty string; Slashdot seems to strip out this auth information from my URL) to get an idea of what the repository looks like.

These are examples of some of its features:

• PDF generation
• Tagging for articles
• Parsing access logs to generate stat pages (properly integrated with everything)
• Syntax highlighting (uses GNU enscript, so it supports around 50 languages)

Re:The simple answer

[Zontar The Mindless]

DocBook rocks.

We use DocBook XML for the source format of the MySQL Manuals, and SVN for version control. We maintain 3 distinct versions of a >1600-page software manual this way, in numerous translations. We produce end-user docs in HTML, PDF, TexInfo, plaintext, CHM, and a couple of other formats. These include the online manuals at dev.mysql.com which get updated 4 times a day from our SVN repositories. We also maintain the Internals Manual using this system. It's also relatively easy for us to produce documentation that's either standalone or integrated with larger documents, such as the Connectors manuals.

We are very happy with this system. Our users seem to be also.

I use oXygenXML as my principal XML editor. So do some of my teammates. It's thoroughly DocBook-aware and does nice transformations of shorter DocBook documents into HTML and PDF. It also validates, pretty-prints, and does a good job performing diffs and merges between different versions of large (100+ K) documents. (It also provides for editing and debugging XSLT stylesheets, although I don't personally use it for that at present.) It's available on *nix, Windows, and Mac (yes, it's a Java GUI app, but it's remarkably fast and stable one). It's neither libre nor gratis, but it's well worth the money, and much cheaper than the (other) commercial alternatives. If you are working hands-on with large amounts of XML in a production setting, I strongly recommend that you check it out.

Re:Reasons _NOT_ to use subversion:

[PeeCee]

Your post is incredibly misleading, if not plain wrong. I will assume this is because you don't actually have any experience with Subversion, so let me address your points one by one.

1. branching is woefully inefficient on the storage side

No idea what you mean here; on the contrary, branching is incredibly efficient. The fact that creating a branch means creating a copy of the whole trunk does not mean every file in the repo is physically copied; all copies are "virtual", and files are only copied when they are actually modified. What this means is you can branch a directory with 10 or 10000 files in exactly the same time and using exactly the same storage space (both close to zero). See the "Cheap Copies" sidebar.

2. merging is (practically) unsupported

Merging is supported just fine. Granted, merge tracking is not supported (yet; it's planned for a future version), which means you have to keep track of your merges yourself. However, with a bit of discipline (for instance, writing in your commit log messages which version you are merging in) this is not too hard at all for the vast majority of cases.

3. there is no rollback from a commit, because....

This is more of a philosophical decision; the designers chose to make it so that every transaction is recorded. You want to go back to transaction X? Fine, copy that version as the current version; nothing is lost. There are also (complex) ways to physically do it for the very, very few cases in which it might actually be a good idea; but many of us have found that version control systems which allow the undoing of transactions are a recipe for disaster (I can vouch for this).

4. it uses BerkeleyDB as the management system.. and that is bad because...

As I said before, the "no rollback" thing has nothing to do with the storage system since it was a design decision. Also, BerkeleyDB is only one of the available data stores. I'd argue that FSFS is a lot more popular these days. More will come in the future.

5. Oracle now own Sleepycat software (the makers of BDB)

As I just said, this is close to irrelevant with the existence of the more popular FSFS. Besides, AFAIK Oracle has not said they will discontinue BDB, and I believe it was open source, so if it really mattered I guess it could be forked.

- PeeCee