Collaborative Documentation

This is a bit of a departure, but I did something at work that is a profound application of not new technology.

If you have several people editing documentation where that documentation has various “options”, and wanted this to be stored on a server with all of the versions, how would you do it? Microsoft Word doesn’t make this easy. It is a binary format that depends on the specific version, printer driver, and can corrupt a document if it gets too big. Plus, how do you handle the “options”?

Enter LyX and subversion. LyX is actually just an editor that creates LaTeX documents. LaTeX compiles to PDF, which is a standard created by Adobe, but by no means requires Adobe software to view a PDF.

SVN, git, CVS and other revision control softwares have been used in the software world for a long time, so why not use this and all of the accessory tools, like TortiseSVN to enable this.

LyX also has the benefit of being very powerful, but in a different way from Word. You can split a document up into many files. Have “branches”, where some parts of the document are conditionally shown. We use that last feature to have one install document cover Windows 2003 AND 2008, PostgreSQL AND SQL Server, with only the very specific bits inside of a branch. Bibtex to make bibliographies a piece of cake. Good math layout.

One of the incredible features of LyX and SVN specifically is that since LaTeX is a text-based format, if 2 people edit different paragraphs of the same file, SVN can merge the changes automatically. Even if those changes were made without an internet connection, and sent to the server later.

A Wiki has some/many of the features, except that it depends on an active internet connection. With a revision control software, I have a local copy of the documents that I can edit, commit, fork, delete, or really do anything with, and other people in my team can optionally get my updates, all with the server keeping a log of revisions committed to it.

Everyone I have really introduced to LyX at work has started using it for personal documents, either for the branches, or other features.

With Word or LibreOffice, which create binary formats by default, how do you version them? Allow many people to edit them at the same time? Share them? Make sure that they print correctly regardless of the specific viewer they are using?

One thought on “Collaborative Documentation

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>