Proposal for multi version documentation

[fzipi]

Some parts of our documentation will face the problem that they need to describe different major versions, with non-compatible changes.

After reviewing a bit our options, we can:

• have a base file that can be included. This base file should be (somehow) independent of the version. For version-specific stuff, we use the include shortcode from the theme
  An example layout for this is:

base/install.md (base with no "specific" version)
v3/install.md 
  - (include "base/install.md)
  - add specific content (files, etc)
v4/install.md
  - (include "base/install.md)
  - add specific content (files, etc)

Another option is to use tabbed content with a specific version. This has the advantage that you always have the content in one file.

Let me know what you think.

[fzipi]

☝️ @theseion @RedXanadu @dune73 @lifeforms

[theseion]

I like the idea but I think it might be hard sometimes to find sensible common content for the base. We'd have to try, I guess.

Depending on the difference in size between base and the specific version, it might be simpler (or better for reading) to use "fold outs". Something like this:

some base content.
-------------------------------------
> unfold version x content                  |
-------------------------------------
-------------------------------------
> unfold version y content                  |
-------------------------------------
more base content

That's not necessarily beautiful but if the version specific contend is only a couple of lines long it might be worth it.

One thing I'd love (but probably can't have) would a version selector that sets the value of version variable (while not necessarily impossible, it doesn't seem to be easy to do with Hugo, e.g., setting / reading URL query params). That way, the entire documentation would be specific to the selected version instead of having different pages for different versions.

[RedXanadu]

I would suggest keeping things simple: have a v3 documentation and a v4 documentation, separate. v4 stuff can be updated as we go; v3 stuff can be frozen and preserved for future reference.

Maybe the landing page can be the common bit, and then it branches off from there. There's currently no version specific information on the landing page, so it can be common across versions.

Tabs are a nice idea, but in practice we'd end up with tabs everywhere and I don't think it would be easy to navigate or keep updated.

[dune73]

I do not like the redundancy of maintaining separate branches of the same documentation. But at least it is always clear what to do. Anything else would be several factors more complex from my perspective.

But I am not married to any solution, as long as we are able to satisfy CRS3 and CRS4 users in parallel for several years.

[fzipi]

@dune73 @theseion @RedXanadu I think we are getting to this one quickly... for now we are going to just use one branch (main) for all documentation I guess...

[theseion]

Makes sense.

[dune73]

Agreed

[dune73]

I see CRS3 documentation as becoming more and more stale and CRS4 documentation being actively maintained.