Proposal: Remove Docs Versions

[plumbis]

Background

Today we maintain a docs directory for each currently supported version of Crossplane. When the community releases a new version of Crossplane the EOL version directory is deleted and the master folder is copied into a new folder for the new release.

What's Wrong?

This approach has exposed a few problems that we've tried to address with varying levels of success.

• Outdated bookmarks - since the URL structure maps to the version, i.e., v1.10 = docs.crossplane.io/v1.10/... when the version is EOL the links break. Redirects would be nice but are unmaintainable
• Algolia search results - The algolia search results aren't great (related Improve Search Results (include version) #202). A major problem is that multiple results are returned for each version that matches.
• Google search results - similar to the algolia problem, the google results tend to have major lags in updates and most google results are for older versions. Attempts have been made to improve this by dynamically generating and indexing /latest but the success is mixed.
• Duplicated content - It's not that much work but we still end up backporting/copy+pasting content across pages to keep things in sync.
• Content organization - Having version specific docs led me to make "user docs" that are focused on the version-specific thing and a "knowledge base" that is less version dependent. However, this has created more confusion around where to find or put content, for example, Move Composition Revision and Composition Function guides to v1.11? #316 , Link to Composition Revisions, Functions, etc from "main" Composition docs #323.

Suggested Fix

Remove "version" as the organizing element in the documentation. All content would be at the "top-level", for example /concepts and /software instead of /v1.11/concepts and /v1.11/software.

What about features that are only in a specific version?

Any new features in a version would be tagged either at the top of the page or when discussing the feature. We already have something like this with XFNs. For specific features and knobs this would actually provide better tracking of when something was introduced. Today new knobs just appear in the docs where they weren't in the previous version.

How do we document things for the next release?

We start using a release branch when any docs work starts on the next release. Things specific to that new version would go into the release branch and it would be merged back into main when the release is cut.

How does this solve search or bookmarking?

Now there is only a single canonical version of a doc/guide. Bookmarks point to a page that (in theory) doesn't get a new URL every 3 months.

What about old bookmarks

For the fixed, existing set of docs we can build redirects.

What happens to the KB?

The KB flattens into the docs as well. The existing KB sections ( config guides, integrations, installing/upgrading) become top level or have their content moved into better top-level locations

[jeanduplessis]

@plumbis how would we handle the situation where something existed in version X, but was removed/substantially changed in version Y. If a user is on version X and looking for documentation around this topic that was removed/changed, how would they find it?

Could we not create version snapshots of the documentation? I.e. we have a flat structure like you propose, with the latest version always on the main branch. We then use tags/branches to keep track of old releases.

[plumbis]

This actually brings up another point I forgot to add which is the creation of a "change log" to track what's new across release and what was changed/added in the docs. Something like this. https://devcenter.heroku.com/changelog

Tagging in GH is fine with me as well.

[negz]

We then use tags/branches to keep track of old releases.

This is what we did before the current iteration of the documentation. The docs lived in the crossplane/crossplane repo and were thus inherently coupled to Crossplane releases by their release branches. I personally strongly prefer release branches over release directories (whether those branches live in c/c or in c/docs).

Touching on a few of the "What's wrong" points:

• Outdated bookmarks - Is this a symptom of the Google Search issue? I believe we started deleting old documentation branches because they were showing up above newer branches in search results. I imagine if we could avoid deleting old documentation then links would not break, and folks would see the "you're looking at an old version of the docs" warning.
• Duplicated content - I feel like this would be less of an issue with release branches, but I'm conscious that I'm saying this from the perspective of someone pretty familiar with git. I think in our space though most contributors are familiar with git (just look at how many folks want to use GitOps to manage Crossplane resources).
• Content organization - Pinning everything to a version would be easier for my brain to handle, even though some things are much less version-specific than others.
• Google search results - Yeah, there don't seem to be many options here apart from not keeping old versions of the docs around. This certainly didn't work any better with release branches vs release directories.

[negz]

I just did a few Google searches to see what happens for other projects:

• "knative service" took me to https://knative.dev/docs/serving/. They have a docs version dropdown that takes me to the landing page (not the page I was on) when I click an older version - e.g. https://knative.dev/v1.9-docs/.
• "istio gateway" took me to https://istio.io/latest/docs/reference/config/networking/gateway/. It's unclear to me what version of Istio these docs pertain to, and I don't see anywhere to select a version.
• "kubernetes daemonset" took me to https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/. They have a docs dropdown that takes me to the same page on a previous version. Interestingly the version is in the domain name, not the path - https://v1-26.docs.kubernetes.io/docs/concepts/workloads/controllers/daemonset/ - I wonder if this helps with Google search results?

[negz]

the creation of a "change log" to track what's new across release

Do you mean Crossplane release or docs release? https://github.com/crossplane/crossplane/releases intends to cover that use case for the former. My preference would be not to duplicate it.

[plumbis]

@negz -

Outdated bookmarks - Is this a symptom of the Google Search issue? I believe we started deleting old documentation branches because they were showing up above newer branches in search results. I imagine if we could avoid deleting old documentation then links would not break, and folks would see the "you're looking at an old version of the docs" warning.

This becomes a maintenance and build problem over time. It's hard to leave incorrect info or typos in published docs so the maintenance still happens even if the version is EOL. The other problem is it will make docs builds (local and for PRs) longer with the more content we have.

Duplicated content - I feel like this would be less of an issue with release branches, but I'm conscious that I'm saying this from the perspective of someone pretty familiar with git.

I'm not sure I'm following. Are you talking about the old "backport" tag/action?

Content organization - Pinning everything to a version would be easier for my brain to handle, even though some things are much less version-specific than others.

Generally I agree and it's why it's not something I've raised before. My take is that most of what's in the Crossplane docs doesn't tie to a version (i.e. Concepts) or if it does, it's clearly marked (ie., XFNs). I suspect (and some of our metrics support it) that most users just go to whatever is $latest based on where the docs send you. Most readers aren't changing the version numbers.

Do you mean Crossplane release or docs release?

I would vote to duplicate it for discoverability. New Crossplane releases already trigger a docs issue so it's unlikely that we'd miss copying the release notes from Github to the docs.

• Knative links to Github
• Istio has site updates.
• K8s links to Github

[plumbis]

I thought it may be easier to discuss this with a concrete demo.

https://deploy-preview-449--crossplane.netlify.app/

Calling out a solutions to specific concerns:

• Introduces the concept of "release notes" (or what's new)
• Adds alpha, beta and v1 versions to top level features (to the right of the heading).
  • For features that are only alpha or beta only the available versions are displayed. For example: ESS
• Uses a note to indicate when the component of a feature is introduced or show modification history. For example, Observe only resources and composition validation
• Creates a schema revision table to track changes to schemas of APIs. For example, adding defaultCompositeDeletePolicy to XRDs

[plumbis]

Suggestion to add "last updated" to an individual doc.

[shanecmiller23]

Looks good to me. My main feedback point was Pete's previous comment as I think most people will be curious about what's been updated when they're in context of a specific guide

[plumbis]

That's great feedback @shanecmiller23! I've added a Last Updated field that pulls the timestamp from the git commit timestamp.

[jbw976]

@plumbis thank you very much for helping everyone understand the impact of this change better by preparing a preview and calling out the changes to note in #439 (comment) - that's really quite helpful for getting everyone aligned 🙇

A few thoughts below organized into high level themes:

Burden on the reader

my biggest concern with removing versions completely is that it puts the burden onto the reader/user to figure out what exactly in the docs page they are looking at applies to the crossplane version they are using. A good example of this is the table that shows what versions certain fields were added, IMO that places too much burden on the user vs the alternative of giving them a version of the docs that accurately represents the version of crossplane they are using.

we often see folks that are not running the latest crossplane release (for whatever reason), so it is a non-zero group of people that will be looking at our docs for older versions.

Git, release branches, backporting

I don't know if it's worth the effort now, but I do personally miss having release branches that contained the docs for each version of crossplane we support. That creates a very clean logical separation between points in time and supported versions of our docs. It removes duplication of content and there wouldn't be a need for splitting between versioned and non versioned content. It's all the same (versioned) and the mechanism is release branches.

IMO, backporting a change to a previous version was very easy esp. with out automated backport bot that opened the PR for you. If there are instances where we're having trouble with git, my instincts are that they could be addressed by a small workflow adjustment for folks having the troubles. I also think that git is fairly standard today and most all folks contributing to our docs will be familiar with it.

Google search results

For any issues we're having with Google search, we could be more aggressive about our removal requests. For each release, we request a removal of content from the oldest previously supported release that has just reached EOL (see last item in release template), but we could extend this to be for all previous versions, so that the only google search indexed version is latest.

TL;DR - Summary

• Removing versions completely is not ideal IMO
• I miss having release branches and I think it elegantly solved some issues we're now facing without them
• We can spend time together to make git workflows easier
• We can remove all versions but latest from google search in the search console

[plumbis]

After discussing with Nic and Jared, we won't move forward with this. Thanks for the detailed feedback everyone!