[xorcist]

> you probably want your docs updates to be coordinated with your product releases

People keep saying that but I can't help to wonder if they're every on the receiving end of documentation.

Documentation isn't code. It may all be text, and share other similarities, but it's something fundamentally different. You can't substitute code for docs, or docs for code. The above reasoning is what ends up publishing /docs/5.3/chapter1/installing.html. Reading documentation for a specific version of the product is not desirable.

To understand the product, it's very relevant what happens in version 5.4, and I should not have to diff different releases of the docs to find out. The documentation should say clearly that this function will be deprecated, or look different in the next version. In short, documentation should neither be branched with code, nor released with it. It should live in parallel and describe not only how the product works, but more importantly why it works like it does.