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:
- When the underlying code is changed
- 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.
