Consider versioning documentation

[chipzoller]

Problem

Kubecost has many versions under its belt at this point with many changes across those versions. The documentation currently jumbles these all together and makes references of, sometimes, deprecations or inclusions 20+ minor releases ago. This has the side effect of making documentation more lengthy than it needs to be, conflating different aspects of the technology, confuses readers as they aren't really sure what's fully applicable to their installation, and makes maintenance more difficult.

Solution

Consider starting to version the docs by using GitBook's collection publishing feature. An example for what that could look like once complete is here.

[brstuder]

We've looked at this before. What this would involve in order to version would be a duplication of the entire space with every update, which I don't know if this would be feasible long-term the way versioning can be used for different languages in GitBook's example. Generally, I think we expect users to be using the most recent version of Kubecost where possible.

[chipzoller]

What this would involve in order to version would be a duplication of the entire space with every update

Not necessarily. Versions are maintained as branches and all changes go to a main designated branch. Regardless of whether they come in through the GitBook interface or a traditional PR, it's a merge commit. If the contents are applicable to multiple versions, that commit gets cherry picked to the applicable branches. It's not reasonable to maintain docs versions for releases from the beginning of time, but perhaps starting with the last 6-10 minor versions would be good enough.

[srpomeroy]

Maintaining versioned docs should also be easier once we change our release cycle.