PrevUpHomeNext

Sidebar: Version Control

Software must adapt to survive. Features are added, bugs squashed; maybe the UI gets a makeover, maybe configuration files are replaced by a database. Customers do not usually get exposed to this state of flux. Typically, they are shipped stable and tested versions of a Product—though they may also expect to receive patches against these versions, fixing critical bugs for example.

Software developers depend on their version control system to manage both the formal, released versions, the patches, and the ongoing development version, and to maintain the connections between these versions. Computers are good at isolating the differences between versions of a source file and at copying these differences between the different branches of a code-base. Thus, a programmer can (for example) fix a bug once, and the version control system can then be used to safely apply the fix wherever it's needed.

In a large code base, the version control system can be configured to allow a team of programmers to work on the same set of files—and even on the same file. The version control system can make sense of concurrent modifications, and merge them accurately; and in the rare situations it can't, it fails safely.

These considerations apply equally to the user manual, whose versions must map to versions of the software. By choosing suitable documentation formats and adopting version control, authors can realise the same benefits.

In fact, the leading open source version control system, Subversion [Reference: Subversion], explains the concept of branching a project using the particular example of a document -- a handbook, in this case. See: http://svnbook.red-bean.com/en/1.1/ch04.html#svn-ch-4-sect-1 for more information. Note also that the Subversion documentation is written in DocBook.

Copyright © 2006 Thomas Guest

PrevUpHomeNext