What should versioned documentation look like?

[keynmol]

This is a fun one.

Goals

1. As a library author (not me lol), I'd like to be able to have my documentation compiled against multiple versions of my project.
2. I'd like to have a unified UX for switching between versions
3. I'd like to be able to update and expand documentation for different versions independently.

Approaches

There are several ways of doing it that I know of, and they're orthogonal:

1. Weaver publishes all of its artifacts from the same branch, and the documentation for each version is built only once.

   • There's an Ammonite script that "freezes" the documentation for previous tag in the separate branch
   • This means that a) documentation for previous versions cannot be expanded (see cats-effect example to see why that's a problem) b) documentation is frozen statically - so whatever version of mdoc generated it at that time, that's what you get

2. Cats-effect takes a different approach - binary incompatible versions of the library are on separate branches, and so are the .md files for each version

   • This helps tremendously in the cognitive load of just being able to contribute markdown file changes to a branch and they'll be built against the version you have locally
   • The separate docs branch is updated asynchronously using dependabot - submodules point at CE3 and CE2 versions, which can build their markdowns
   • Any changes to documentation (even if they're not version-specific features, such as ecosystem documentation) need to be duplicated
   • There's great flexibility in how the site actually looks - you can structure the versioned parts statically, and only change the compiled markdowns.

Proposed solution

The landscape is changing. As often as the butterflies claps its wings, a new RC of Scala 3 is released, a new CE version emerges from the cocoon and all of that has to have a nice website go with it.

But we can't have nice things.