Version registry documentation

[lukehoban]

It would be nice if our docs were versioned so that users could navigate directly to the 1.8 docs. This may make sense initially just for API Docs (each of which versions independently).

[dstine]

Just adding my comment from Slack:

I find this feature incredibly useful, especially for emerging projects which are advancing rapidly, introducing significant new features (often independently transitioning from preview mode to GA), making selected backwards-incompatible changes, and so on. There is no substitute for direct navigation to e.g. the 1.7.1 Python SDK or 1.9.0 TS SDK, etc.

[ringods]

@lukehoban definitely have a look at Antora. If you want an example of a big site created with this tool:

• https://docs.couchbase.com
• Source entrypoint: https://github.com/couchbase/docs-site/blob/master/production-antora-playbook.yml

And a smaller example:

• https://terra-farm.github.io
• source entrypoint: https://github.com/terra-farm/terra-farm.github.io/blob/site/site.yml

The biggest advantage of this tool:

• works with docs out of multiple repositories
• uses branches and tags to mark the different versions
• uses AsciiDoc, which is a more extensive but fully standardised markup language.

[thoward]

This ticket was originally intended to apply to our entire documentation site, however in the past 4.75 years we haven't been able to make progress on this. Currently, our Hugo-based site is a bit too complicated and our engineering resources too limited to be able to implement versioning any time soon, and by that, I mean, probably never for this version of our tooling. We've been discussing moving away from Hugo and on to a different CMS. For that reason, I think we should include versioning as a requirement of whatever our next documentation tooling is, but should not anticipate upgrading our Hugo-based site before that transition happens.

The registry documentation is the subset that would most benefit from this. This is already built separately from the rest of the site. We just fully transitioned ownership of this from the docs team to the providers team, who has plans to expand the coverage of the registry and potentially to implement it as a dynamic site rather than a fully static site. During that process, they intend to include versioning as part of the updates.

So, I transferred this ticket to the registry repo, and reduced the scope in the title to indicate that this will apply only to the registry portion of our documentation for now.