When to add version numbers to documentation

Question

It is often useful to document when (i.e. in which versions) a feature was added, marked as deprecated, etc. For example:

Function FooBar(x, y, z)

Foos x with y and bars them with z.

(Parameter z was added in version 1.2)

I'm wondering when and how those notices are best added, and I can think of two alternatives:

1. When the underlying code is changed
2. When the release is made

Alternative 1 has the benefit that it keeps code and documentation in sync. However, it requires me to know the next version number in advance. In my experience, that is often not possible, because the feature may be delayed (even though the code is already there) and hence not end up in the originally targeted version.

Alternative 2 avoids that issue, but complicates the release process because you have to go over your change log and update the documentation accordingly.

Answer 1

This depends on how you plan which features go into which release. For example, if any feature that is merged during a certain timeframe will make it into the 2.4 release, then you can use that version number directly.

If you do not know the next version, it would still be reasonable to update the docs immediately, precisely because it's best to keep code and docs in sync as much as possible. Instead of a fixed version number, use a placeholder, e.g. in Sphinx I write .. versionadded:: NEXT. You could create a check for your release QA process that all placeholders have been resolved. Searching for a placeholder is easier and quicker than trying to remember which documentation has to be rewritten.

Answer 2

The short answer is "when it is needed". Documentation doesn't live by universal rules, it's a matter of convention and doing what makes sense for your current context.

That being said, there's a reasonable line to be drawn here that versioning and actual documentation context should generally be separated so as not to distract from each other.

(Parameter z was added in version 1.2)

This is less optimal, as you're eventually going to end up with a document that spends more time pointing out its revisions than it spends informing the reader of the actual content.

Just to prove my point, if we end up changing many things, you'd get something like:

Function FooBar(new_x, async_y, z)

Foos new_x with async_y and bars them with z.

(Parameter z was added in version 1.2)
(Parameter new_x was added in version 1.7)
(Parameter async_y was added in version 2.8)

This is the same principle as your example, but it's become clearer that the versioning logic is a distraction and doesn't really contribute to explaining what FooBar actually does.

A better way to do it would be to have a changelist in the document, but separate (e.g. as an appendix). Many companies I've worked at kept a compilation of all changes (grouped per version number) at the back of their documentation.

One of these companies used a specific color coding, where new features were highlighted in orange in the documentation itself. Features that were new in the previous version were a lighter orange, and features that were new in the version before that were highlighted in an even lighter orange.
This of course takes more effort to do, but given the complex nature of the documentation it got great feedback from the company's customers, who could now easily spot potential breaking changes to their implementation of the product.

---

That being said, if you reasonably expect users to use different versions of your software, and you want your documentation to apply to all of them, then pointing out version differences is justifiable, e.g.:

Function FooBar(x, y, z)

Foos x with y and bars them with z.

(Parameter z is only available in version 1.2+)

Whether you create separate documentation per version or keep them merged is your choice. It depends on how complex the differences between versions are.

---

I'm wondering when and how those notices are best added, and I can think of two alternatives:

1. When the underlying code is changed
2. When the release is made

Your developers update the documentation when they change the code, but the (updated) documentation only gets released to the customer when the new version (in which this update occurred) is released.

If you delay writing documentation until release, then developers are going to forget some thing to mention.

If you update the consumer's documentation before release, then your documentation is going to talk about features that don't even exist to the consumer yet, which is not good either.

However, it requires me to know the next version number in advance. In my experience, that is often not possible, because the feature may be delayed (even though the code is already there) and hence not end up in the originally targeted version.

Note that "updating the documentation" doesn't mean the updates have to be put into the releaseable document. You can track changes in another location and insert these into the releaseable document just before release. That's a matter of how you choose to organize things.

If you keep a separate changelist of developed features and only inject those notes just before release, then you'll know the version number.

Alternative 2 avoids that issue, but complicates the release process because you have to go over your change log and update the documentation accordingly.

Yes, it requires documentative action close to release, but you can prepare as much of the work as you can.

Don't go mining in the changelog after the fact (you risk forgetting things), just keep track of changes as they are made and compose them into the official documentation when you are able to do so.

Answer 3

You might also benefit from maintaining a feature log.

When you implement the change, add an entry to the log. The beauty is that it serves as a short-list of changes in a branch, and can be used to figure out how to bump the version based on the number/kind of major/minor/patch level changes.

When versioning they can be followed up either automatically or manually, to have a version number inserted.