Collaborative documentation tools
Version control is one of the unquestioned foundations of software development: while there may be discussion about which version control system to use, whether or not to allow concurrent modification, how to secure access to the system etc., noone would think of undertaking any serious project without using version control. Quite simply it’s how a team of people can work on the same codebase at the same time.
Yet recently I described a project where version control was not used. Instead, the team relied on ad-hoc file sharing, circulating source files by email and by copying them to a shared folder. Concurrent modifications were prohibited. System integration was left until the last minute. Inevitably the project manager worked through the night to meet the delivery deadline — a proven technique for bug creation. What’s worse, noone on the team really questioned this mode of operation.
Why?
Because the final system was a document. Because the source files (the sections of this document, that is) were edited using Microsoft Word. Because the team — a combination of sales people, business managers and technical experts — knew no better way of working 1.
The sad truth is, I don’t know of any documentation system which could have coped with the requirements of this project. Version control isn’t the problem. Subversion (for example) is more than up to the job of managing the source files, by which I mean not that it allows secure, networked access to the files, backups, revision control and so on — that’s a given; but rather that it comes with user-friendly clients such as TortoiseSVN. You don’t need to be a programmer to use TortoiseSVN.
LaTeX and DocBook
No, the problem is with the documentation systems themselves. You do need to be a programmer to work with a system based on LaTeX or on DocBook — or at least to give up Microsoft Word in favour of such a system. Yet the benefits, if you can make the move, are substantial: you can assemble documents from separate sections, you can view differences between versions, more than one person can work on the same section at the same time, you can generate various output formats from a single set of sources, branching and merging become possible, as do more sophisticated text transformations, and searching multiple documents becomes a snip.
Google documents
I recently tried out the Google documents word processor, which I’d rather assumed I’d like. It has got many things right — document access, for example. You control who can view the document, who can edit the document, and shared access is as simple as an internet connection. Integration with the email client was equally sweet, assuming you use gmail that is. Document versioning and differencing is also in place. Unfortunately I’d say there’s still some way to go with the basic document editing, which I found sluggish and clunky.
I wouldn’t recommend it, at least not yet, but, like the team I described, I don’t really know of anything better. Collaborative, networked documentation tools are the way forwards, I suggest; and I think these tools could usefully steal many ideas from successful software development tools. They’re just not there yet.
I’ve experienced worse. At one place I worked software development activities were organised into separate projects. Each project had its own documentation folder on a networked drive; beneath this folder a number of standard subfolders contained design, planning, specification documents and so on. Documents within a project were indexed using a spreadsheet in the top-level folder. A master spreadsheet indexed all the spreadsheets. Each project had a project number. Each document in each project had a document number. There were spreadsheets containing the numbers. Documents included version numbers in their filenames: N237571_tasklist_V37.doc. To edit a document you had to copy it to its new file name then edit its properties to set the internal version number equal to the internal one, then fill out the document history form. To revert a document, someone had to dig through the backups. Everyone had write access to everything. Concurrent modifications were outlawed. I shudder at the memory.
Articles