Semantic versioning for documentation

15 Dec 2015

Why we need semantic versioning for documentation

Semantic versioning is not just an easy, logical way to assign version numbers to your code: it guarantees that automated dependency systems can reliably work with your code. It also helps human readers of your code, since automatically generated API documentation can clearly indicate the version of the source code.

User documentation and testable specifications, on the other hand, do not always change in lock-step with source code: a bug fix might result in a new release of a package without any change in the specification, for example, or the specification might be clarified or corrected without requiring any accompanying change in the implementation. For these reasons, it’s not enough to indicate the version of the source code being documented (although that is essential). We need a way to identify as well what version of the user documentation we’re reading.

A semantic versioning model for documentation

I’ve tried to apply the syntax and logic of semantic versioning to user documentation and specification documents. The documentation is identified by a three-part version number in the form MAJOR.MINOR.PATCH following the syntactic requirements of the semantic versioning specification. The logic dictating when each part of the version number must be incremented is analogous to the logic for changing the version on source code:

1. MAJOR version: increment when the documentation applies to a new release version of the code.
2. MINOR version: increment when the documentation expands coverage of an already released version of the code.
3. PATCH version: increment when an error in the documentation is corrected.

An example

You release version 1.0.0 of your definitive digitalscholar widget; you simultaneously release version 1.0.0 of the user documentation. It prominently includes automatically inserted references identifying the current version of the source code.

You fix a bug, and release 1.0.1 of digitalscholar. Nothing in the documentation needs to change. (In fact, the code and the documentation now agree!) You leave the documentation at version 1.0.0, satisfied that it clearly states that it documents version 1.0.0 of digitalscholar. Clear release notes accompanying 1.0.1 of your source code should prevent confusion when users of version 1.0.1 pick up documentation for version 1.0.0.

You later add a new section to your documentation, addressing FAQs that have come in from users of digitalscholar. You rebuild the documentation as version 1.1.0; automatically inserted references to the current version of the source code will now point to 1.0.1.

You implement a new feature in digitalscholar that does not break the current API. Following semantic versioning principles, you now assign your source code the version 1.1.0. You simultaneously release documentation for it: this documents a new release, so you assign the documentation 2.0.0. You immediately notice a typographic error, fix it, and release the fix as version 2.0.1, clearly labelled as documenting version 1.1.0 of digitalscholar.

Practical application

With modern build systems such as gradle, it’s straightforward to track separate version numbers of source code and documentation and include each as appropriate in automatically formatted documentation. Keeping a separate series of versions eliminates potential ambiguity about the relation of documentation and code that are modified and released at different times. Applying an analogous logic for version numbers on documentation should be helpful to readers familiar with the logic of semantic versioning for source code.