Things to consider when thinking about versioning documentation
2 viable schemes available (for Hugo/Netlify)
Dropdown menu navigation code examples
trade offs
Readers: ease of navigation/understanding
Maintainer: how hard is it to update when it's time to cut a new version?
Necessity: YAGNI - you ain't gonna need it
Navigation: Differences between versions (how do you deal with pages that have been added, removed, or moved between releases?)
Searchability: Does the duplication of pages affect search results? How do you manage result priority between versions
Localization/internationalization: how does the added complexity of language/locale versions affect the version system
Compartmentalization: Does all of the site need to be versioned?
How do we avoid versioning the entire site if only Documentation versions are the goal?
Switchability: How easy is it to change versioning schemes
Because Hugo is a static site generator, and
Netlify abstracts a lot of the server away
Query Strings and Cookies don't really work for a Hugo / Netlify site
Scores high on: - Maintainer ease of updates - Compartmentalization
This is probably the easiest way to start versioning.
Scores low on: - Localization / Internationalization
Can make code more complex
One of the things that make this a good example is how Batard (2020, L8-L18)
manages the navigation in the `/site/layouts/docs/versions.html` file,
particularly the use of the `replace` function to ensure that when the links in
the dropdown menu are built, the versioned links reflect the currently loaded
page:
Can make configuration less complex
Scores high on: - Localization / Internationalization
Scores low on: - Compartmentalization
Scores low on: - Maintenance, each version is its own site
The subdomain scheme uses some simpler template code to generate links, only having to update the `.url`, but the Hugo config file is made more complex.
same style of dropdown function as before, made simpler
dropdown example is made simpler because the config is more complex
and because the server setup is more complex
and not, for instance, the blog
some work is being done on k8s to address compartmentalazion, but it is ongoing