Version Control for Documentation?

CodeNation asks: "I'm a coder in smallish (~50 staff) company with a ~20 strong development team. We, the development team, have been using CVS, and CVSWeb to manage our source base for a couple of years. In the meantime, our corporate documentation has become a complete mess. By 'corporate documentation' I mean content such as Word documents, Powerpoint presenations, and Excel spreadsheets. Anyway, I was recently asked by the one of the bosses to put a document version control system in place for this corporate documentation. All this, and the system has to be usable by the non-technical." Ask Slashdot has touched on a similar topic but it's been about 2 years since that article. Has there been any headway in this area?

"Now, this would be a trivial task if:

• The documents were text-based (i.e. the file formats weren't binary)
• The entire company understood how to use CVS

However, neither of the above are true.

I took a look at CVSWebEdit, but unfortunately it's not quite there yet in terms of stability and usability.

Does anyone have any suggestions for a possible solution? What are you currently using for document control (remember these are Microsoft Office documents). Also note that although the developement team works on Linux boxen, the non-technical staff works in a Windows environment.

Thanks for your help."

Xanadu of course.

Xanadu [xanadu.com.au] was made for this.
Joseph Elwell.

I think you're missing the point

Corporate documents have much different needs than programs. Documents need to be searchable, categorized, approved, etc. You need something that will tag a document with

* Current Version
* Related Categories
* Awaiting Approvals
* Approvals Received
* Place in the system
* What time to re-review
* Notes for a document

This way, anyone can easily find a document, and find any past versions. New documents will have to go through a formal approval process, and people will be automatically notified when documents need to be re-reviewed. Notes can be attached for clarification and questions.

CVS can do versioning, but not the rest. And, CVS's versioning is MUCH too complex for what you need. You don't need branches/tags/everything else with corporate documents. You are never going to merge between branches. You just have the document and its version.

You can use a network directory if you do it right

I've been in your shoes, and my opinion is that it's better to keep it simple, but organized.

I don't like using CVS with nontechnical people who haven't been trrained for it. They are as likely to accidentally overwrite the new version of the doc with the old as they are to save themselves any trouble. So, if you go with CVS, definitely factor in training for everyone.

But, if that won't fly, maybe you should just consider using a plain old network directory, with some careful setup.

Basically, use grouping and network access privileges to give each workgroup their own directory noone else can edit. Each software project has their own subdirectory, and each set of docs for a version of the software a deeper subdirectory. Keep the different versions of the docs totally separate (don't try to be clever and have a shared graphics directory), and archive the old docs in zip files so that nothing gets lost or written over.

That's a start. There is a whole lot more involved in doing this job right: you have to build standardized templates, get the users to enter information for each doc (this can be done easily using a macro that makes them fill out a form when the doc is created), collect that information and set up search tools and indexes.

It's a complicated subject, and that's the short version. If you want to read more, check out my my 16-page Guide to Standardizing and Organizing Documentation [fast.net]. It's not quite where I want it to be yet (second draft but not finished), but I think it might be helpful.

Jon Acheson

Several Solutions

There are several possible solutions to this problem, as I see it. If you want to go the commercial route, Visual Source Safe is the normal standby, or any other commercial source code repository systems would work. VSS has poor merging capabilities, but when you're dealing with Word files or PowerPoint slides, that's not so much a problem (as Office can "version" the files for you -- though make sure to strip the file before releasing it to customers). Also, the upcoming Office XP has Sharepoint capabilities, and is very easy to use (easy enough for your pointy-haired boss to figure out, even).

On the other hand, you could setup CVS anyway, even though you said you'd rather not. There are a few nice win32 GUIs for CVS, so the end-user experience shouldn't be too bad. On top of that, if you use CVS for your documentation, you can keep that in your source tree. One less tree to manage, and you'll always know where the documentation is. And CVS can handle binary files just fine. Just don't expect to be able to merge changes.

Of course, another (less likely) option would be to move all your documents to HTML, or XML with a set of defined XSLs to transform them. That way, you could do merging just fine. However, that's most likely not a workable solution if you deal with anything but Word documents (since word can save to HTML instead of .doc).

Binary File Version Control - problems with it

There are a number of good tools out there for version control - however there are very few that can handle binary files in a "good" manner.

Some issues:

One - Binary file formats - such as MS Word - cannot have diffs run on them that are meaningful - a binary diff will result in a file larger than the two original files. So most version control programs will store binary files as seperate versions - but will NOT show the differences between the versions.

Two - Microsoft HAS some built in support for versions within Word - however this will quickly result in VERY large files - which get increasingly less useable. Also note, that this will be ONE file containing all versions - if you "version" this file, you will have TWO files with different sets of the underlying versions.. sounds confusing? It would be.

Three - There ARE version control programs that have worked with Microsoft to learn how to understand the underlying MS file formats (I believe Clearcase may, possibly MS's own Sourcesafe (which is otherwise a dangerous version control software to use since it can have data integrity problems) and possibly a few others.

So - what would I recommend or suggest?

First - Look carefully at WHAT you are intending to version. Is it a collection of documents (i.e. a full manual)? Individual documents that change over time? A whole project structure (say a website for online help?) Or something else?

Can you seperate out the FORMATING (which might be in MS Word) from the content? For example by using a Master document format - importing TEXT documents into MS Word? This would allow great flexibility in versioning the underlying text documents, keep a smaller MS Word file, and that file could be "versioned" storing copies of each successive version?

Second - For simple document management systems, (which run on Linux but can be accessed by any browser) look at a system like InfoPlace - simple, open source (I think) and easy to use. It is however not a rigorous version control system, but a partial version control system.

Hope this is helpful - I spent 2+ years teaching and managing version control for a very large development operation (1000+ developers worldwide).

Shannon

Chaos to the rescue

You guys should use the document management system that my last company used- total chaos. Every user creates a directory called "Bob's stuff" or "BSR" or something similar. Then all of the files they work on, no matter who else will need them, should go in the "Bob's Stuff" directory. Each file should be given completely incomprehesible names like "ClientData.xls", "JimQuote.doc", or "CSIQ12001rpg.ppt". That way when you need something, all you need to do is find the person who worked on it first and have them remember what they called the file. The set up and maintnence costs of this system are nearly nill. All you need for it to work are employees with photographic memories who never quit or die.

-B

Re:Ultra simple CVS client

If you'd love to check it out, but the links on cvshome.org point to wincvs.org for TortoiseCVS, and that domain, according to NSI whois: Record expires on 08-Mar-2001. So try this link [sourceforge.net] instead, it works!

Shameless plug

Sorry for the shameless plug (I work for Open Text Corporation [opentext.com]), but Livelink [opentext.com] is a great document management system product. It may be out of your price range, but it does allow you to have versioning on your documents, and it has a whole whack of other features that many enterprises demand.

It seems that they're marketing it now as "a highly scalable and comprehensive collaborative environment for the development of Web-based intranets, extranets and e-business applications." Oh dear.

Look into StarTeam

I'd recommend looking into StarTeam [starbase.com] from StarBase [starbase.com]. And this is even despite having been a developer there a while back :-)

As a developer, I usually prefer CVS, but StarTeam works quite well for a whole office, Word docs and all. For the Windows-based world you mention, it seems quite appropriate. They have many different clients, and I've seen it used in mixed Windows & Solaris & Linux environments.

In general, if a shop can't use CVS, and especially if they're using SourceSafe, I can in good conscience recommend it. And remember, friends don't let friends use SourceSafe :-)

IANAL, YMMV, etc. I'm not sure if it will work for you, but it's definitely worth investigating

Re:"Good Developers" can just slap on a front-end.

True... and the problem with the files being binary can be solved by UUencoding them, first.

Subversion

CVS done right. [tigris.org]

Commercial DM Products

Check out the products available from Hummingbird [hummingbird.com], Documentum [documentum.com], and Eastman [eastmansoftware.com]. A long list of document management vendors lives here [google.com].
---

uphill battle

Maybe I'm cynical but your stated goals of

implementing version control and

making it usable by nontechnical people

You face one major uphill battle.

Many nontechnical people have a hard time understanding a hierarchy, or of file types; this is expressly why Windows 95 defaulted to hiding file extensions and the subdirectory trees.

Add to that the complexity of "where in the hierarchy does this file permanently belong," and the question "at what point in time was the file in a condition you liked?," you get into a major learning curve. Describing a sandbox is a task unto itself. Undisciplined developers often grok CVS but still don't use the delta comments in any meaningful way.

That said, VMS is probably your ideal here for simplifying version management. Too bad it was an integration into the filesystem itself, and didn't expressly deal with multiple writers or delta comments.

For those who haven't used VMS, the filename included a version number: name.extension;version . If you neglected to mention the version number in a system call, it assumed the newest. Every file opened for writing got the next version number and left the old versions untouched; every file opened for read-write cloned the newest old version first and bumped its version number. This builds into a large list of ;1 ;2 ;3 ;4 ;5 ... ;632 version for each file. You could easily back them all up, or prune to the newest version.

Re:As much as I hate to say it...

Microsoft doesn't even use Visual SourceSafe internally. It can't handle large projects. They actually use Rational ClearCase for the majority of their Source Control.

Doesn't say alot for the product.

The other thing is SourceSafe has problems with more than 200 projects in its repository. It starts Corrupting the data. Not what you want to see from a source Control system.

----
Just remove the spaces and do the intelligent thing to email me.

Re:"Good Developers" can just slap on a front-end.

Great idea, except that good developers know not to leap into re-inventing a wheel that might already exist, especially at the cost of "a week or two". Don't you think they already have something to occupy their time?

PVCS

Although I can't say it's the greatest system I've ever used, PVCS offers a moderately simple web interface that should work across all OSes. Our non-developers use it to store their documents without too much trouble.

Documentation system...

I have to start a new thread for this comment because _every_ comment that I've read has failed to mention the following solutions.

As a systems engineer for a gov contractor, I needed to make a survey for documentation revision control software. Due to my CS background, I immediately thought about CVS, sourcesafe, and other source code revision control packages. The source code revision control packages were not up to the task of documentation revision control. Since systems engineers deal with requirements, and requirments are stored via documentation, every requirements analysis package comes with documentation revision control software. These packages also help to create documents from templates and databases. Depending upon your needs, these documents keep track of customer requirements from concept through delivery/installation, into maintenance.

There are many systems engineering tools that handle requirements analysis in various ways. Many of them work with MS Office (prolly what your writers currently use), and have built in versioning control. My best source for information on these tools was at the INCOSE tools website [incose.org]. This sites lists tools and checks them for the following features...

Store standard document outlines - used as starting points? User definable templates or modifiable?

Produce architecture views from functional and object oriented (OO) perspectives? Examples: WBS, functional , physical, data flow, state diagrams

Support various physical architectures? (View from a number of levels, Black box, Rack, circuit board, chip)

Enable tailoring to specific standards and requirements, IEEE, ISO, MIL-STD?

User friendly & menu driven (drag and drop capabilities)?

Support a single user or multiple concurrent users?

Input document change / comparison analysis

Visibility into existing links from source to implementation--i.e. follow the links.

History of requirement changes, who, what, when, where, why, how.

Baseline/Version control

Access control (modification, viewing, etc.)

. Support of concurrent review, markup, and comment

Multi-level assignment/access control
Plus many more features.

It is my opinion, that the following packages are up to the task:

Cradle

Doors

rtm

rdt

Caliber rm

If you go the page that I linked, it provides an in depth review of each of these tools plus many more.

As much as I hate to say it...

Microsoft Visual Source Safe.

It stores versions, has a nice, friendly, Explorer-like interface, and runs on windows. Sounds like that's all the management wants. As long as they don't want to branch documents (which I recall being a bit of a bitch), they should be fine.

(All of this with the note that I'm *pretty* sure that VSS handles binaries alright, even though it may not be able to do such things as diffs, even on files in a proprietary format from it's own company.)

DocsOPEN

There is a product called DocsOPEN made by Hummingbird I beleive. We use it at my office. It is WELL worth working into, and it integrates into almost everything windows. There is also a web interface for it called CyberDOCS.

Basically, instead of saving your files to a drive, Docs comes up and asks you to fill out a form. The file gets saved somewhere mysterious, the data goes into a serachable database, and you get on with your life. Later you call it up by searching for it, and you can add a new version when you save it. It's pretty neat. However, it is hard to get people to use unless you beat them over the head.

Re:PVCS

I used PVCS at my last job. My group developed and deployed on Solaris 2.6, even though almost everybody had NT boxes on their desks. We chose to use the Unix version of PVCS, which nominally ran on Solaris, but actually didn't. It actually only ran on HP-UX. We ended up with a really half-baked system where HP-UX machines running PVCS and our development machines NFS mounted a partition served by an Auspex NFS server. We'd log in to the HP-UX machine, set DISPLAY to desktop machine, and check-out into the NFS-mounted partition. Then, we'd log in to the Solaris development machines to develop, compile and unit test.

PVCS for Unix is an absolute and utter mess. DO NOT let yourself be contaminated by the bug-ridden and awful terror that is PVCS. The GUI (Java app) is a heinous, bug-ridden piece of excrement with incredibly poor user interface. The GUI is slow, and has so many human factors problems that developers occasionally checked-in files in the wrong directory. The GUI doesn't do a good job of mapping "archives" to directories, and it doesn't map from directory to "archive" at all. This leads it to offer you a selection of "Makefile" archives, and you get to choose which one. You must understand the internal structure of the PVCS archive directory tree to choose the right archive. PVCS seems to think that all files have an "extension", whatever the hell that is, and if you have files (like "Makefile") that don't have an extension, it won't expand RCS keywords ($Id$, etc). The back-end is equally buggy. We had a more-or-less half time PVCS administrator, whose job included deleting lockfiles that PVCS would occasionally leave around.

The company I used to work for chose PVCS for two public reasons: (1) it's nominally multi-platform (we found out that it isn't, Merant only claims it is) and (2) it had really, really elaborate management interfaces into the bug lifecycle. This makes managers happy, but leads to lots of ugly "WTF do we do with this bug report?" meetings at the end of a development cycle, the day before a release.

I strongly reccomend you avoid PVCS.

HTML is your friend.

Why not use HTML? I've been using HTML for years for all of my documentation. It works perfectly for a cross-platform manual accessable from anywhere.

If you need powerpoint-type presentations, Flash [macromedia.com] is easy to use, fast, and readable on nearly all modern browsers. You can even generate it with PHP [php.net] or PERL [twoshortplanks.com].

Think Weblication....

If you need an easy to use UI, take a look at Xerox Docushare [xerox.com] or perhaps if you want to lean toward groupware look at Amphora [amphora.ee].

"A microprocessor... is a terrible thing to waste." --

Ultra simple CVS client

Check out TortoiseCVS from the CVSHome [wincvs.org] website. It's an add-on to Windows Explorer that adds status dependent color shading to CVS controled directories and context sensitive commands to the Explorer file menu. Comes with a bundled SSH client for secure tunneling.

Easy to install and VERY easy to use, and no, I don't have anything to do with the project. I just use it.

An increasing problem...

Most major word processors include version control, comments, revision history and so forth. A major issue facing law firms these days is making sure that all of that content is removed/turned off before submitting electronic documents to the other side.

It can be very embarrassing to have all of the private comments revealed to the other party when you didn't realize there were there. Increasingly firms are checking for these things as well.

Word 2002, from the Office XP suite, includes a Security Tab on the Options settings. In there you'll find a Privacy section which gives you checkboxes for things like deleting personal information on save and "Warn before sending, saving or printing" a document that has file revision tracking turned on.

-Coach-

Re:"Good Developers" can just slap on a front-end.

Two weeks, one full time developer: $10,000.
Two weeks, one office employee: $600.
Five weeks, 3 part-time developers: $59,000.
Q4 earnings time, the look on the boss's face: priceless.

There are some things money can't buy. For everything else there's Corporate Mastercard.

--
"Fuck your mama."