How to cope with versioning of software documentation and the software itself?

Question

I need some experiences concerning the writing of software documentations and user guides.

When I write formal documents like software specifications, every document gets a version number and in the document there is a change history after the table of contents, where you can keep track of the changes made to the document.

If I'm now writing a software documentation or a user guide for an application, and the software has versioning itself, one could get confused with the version number of the document and the product: e.g. application version 1.5, documentation version 1.3.

What's the common way / best practice to write software documentation? Do you keep track of changes to the documents there? If you print a change history - do you show changes to the product and/or the document?

Answer 1

I think that the documentation and the software are different items, which each have different version numbers. You want to be able to update the documentation without having to update the software number. I would have named it something like:

System Documentation for productX 1.3

Documentation revision 1.7

By clearly including both the software version and the document version in the same place there shouldn't be any confusion.

Answer 2

Why don't you just use version control and use that as the automatic document revision? You can have most systems update some text on checkout.

Answer 3

We tend to use a plain text format for our documentation, mainly LaTeX, and treat it just like source code from a revision point of view: it goes in the repo, we can do diffs and patches, etc. We're not big for change histories in published documents, we can always audit what has gone on if necessary but it rarely is.

As for synchronising code and documentation version numbers, our preferred approach is that v1.1.1 of a document matches v1.1.1 of the software, 3.2.45 matches 3.2.45 and so on. However, in practice we often only have documentation for the first 2 digits (ie 1.1, 3.2) since the third digit is mainly for bug-fixes or performance enhancements. The repo revision number is inserted into the documentation (and in the source code) using svn:keywords should we ever need it.

I'd like to tell you that the same makefile which builds our new version software also builds the new version of the documentation, but we haven't got there yet. We are, however, working on it.

Answer 4

I've encountered this issue at every company for which I've worked that 1) had a significant code base, 2) attempted professional quality documentation, and 3) had separate development and documentation groups.

I have come to agree with Anders, convinced that software and documentation should have different versioning and version control systems. Although similar and having the same target, documentation and code have different lifecycles, which can be fully independent, only being mapped one to the other at release time.

As for generating the documentation with each software build, ask yourself: does that really make sense? Is the documentation historical or is it prescriptive? Any documentation that is generated with each build better have the tools in place to do it. Currently, that only works for API documentation and there are Doxygen-/Javadoc-style tools to support it. That is likely to never be doable for User's Guides and Installation Guides because they are context sensitive.

The need for different version control systems holds, particularly, for the newer structured documentation methodologies. Structured documentation needs to be managed at a much finer level of granularity than source code to be able to efficiently handle something even as seemingly simple as rebranding; usually managed at either the paragraph, sentence, or word level, unlike the file level, which is sufficient for source code. Further, it is generally economical for document elements to be shared among multiple products or departments (engineering, marketing, ...). And, for this level of documentation sophistication, only a content management system is sufficient for tracking content and managing change; the CVS-/SVN-/Perforce-/Clearcase-style SCCSs are abysmally inadequate for managing real-world documentation. Using different version management tools ensures different version numbers for documentation and software.

Documentation may even have a higher rate of change than software when the need for handling typos, grammar errors, and corporate style changes is considered.

Separating documentation and development processes reduces dependencies, which is the fundamental metric needed for producing a quality product. Further, late binding is desirable to best accommodate the rapid rate of change and unpredictable events like late feature additions or deletions. Only at the moment of final (or alpha-/beta release) should the documentation version be mapped to the software version. But, I agree with High-Performance Mark that the end user shouldn't see different version numbers. The documentation version number does not need to appear on the document. That number can, within the documentation process, be maintained and hidden from the public.

The only time that software and documentation versioning can be maintained in lockstep is when documentation is a fully-integrated part of the development process. Over the last 30 years, I've seen this becoming less and less the case because there is less formal, upfront design than there used to be, relying, instead, on an iterative, quick-prototyping approach to software development. The original well-intentioned notions of having documentation drive software development have mostly been put aside but the new methodology also hasn't given us improved documentation or software. Whether the documentation is done upfront or as an afterthought, it's still going to double the time it takes to develop a commercial-quality product.