How can we better handle multiple versions of the documentation for a project?

[CharliePoole]

I'm currently maintaining two distinct versions of NUnit Console andEngine. The 4.0 is up to alpha 6 with lots of usage. My documentation is only for differences and is found here: https://github.com/nunit/nunit-console/wiki. My original plan was to completely revise the documentation when 4.0 is released, using the wiki pages as a guide.

This no longer sounds so good. The changes in 4.0 are extensive, many of them breaking. It would probably take me a week or two to completely redo the docs for the new release, leaving users without documentation for that period. In addition, the 3.x docs, needed by users who don't upgrade to 4.0, would become unavailable.

It seems to me that this is a general problem, although my particular case is extreme due to the breaking changes. Even minor releases call for documentation of new features, which is usually postponed because it would confuse users to post documentation for an unreleased feature. Nevertheless, by creating -dev releases, we gave given rise to a community of users of exactly those features.

It seems to me that we need some way to allow for at least two and up to three different sets of docs.

1. The current stable release, which is now on the website.
2. In cases where a release, perhaps a major release, is under development for a long time with alpha or beta releases, the latest pre-release.
3. The latest dev release, representing the current state of master or main.

Questions that come to mind...

• Where do we want ll of these? In the docs repo? Should some of them in the individual repos?
• How can we set things up so that we can very quickly promote a release from one level to the next?
• Do we want to retain a copy of the last previous stable release somewhere? If so, where and for what types of upgrades?

I'll be glad to work on the implementation of this for the console project, if we can agree on an overall approach.

I do have some tentative answers to some of my questions but I'll hold them till others have had a chance to react.

[stevenaw]

I'd agree that this is a general problem and I think whatever solution is chosen here could benefit the framework as well. Even though we'll be trying to minimize breaking changes on that side, there will undoubtedly be new features or APIs which would need documenting.

I don't have a great deal of experience on the documentation side, but I'd be very curious what options could be available to help avoid the same set of problems @CharliePoole identified above