Remove canonical dead-ends

[pepopowitz]

Follow-up to #2577 (and more broadly, #1143).

#2577 introduced the ability to specify canonicals for older version pages that can't be automatically associated with current version pages. It also logs a warning to the build output when the build comes across one of these pages (search for WARN(canonicals) in this build: https://github.com/camunda/camunda-platform-docs/actions/runs/6265686651/job/17015028860).

We should correct as many of those canonical dead-ends as possible. Some of them might be true dead-ends, where content reached end-of-life in an older version, but most of them are probably a result of the content moving to a different URL/document ID.

[pepopowitz]

@akeller @christinaausley this issue represents a one-time pass through all our docs, to find and update pages who point canonically at a non-latest doc. Aside from this one-time pass, it might be helpful for us to consider applying canonicals when we deliberately move content. This could be something we start to look out for during PR reviews -- if a page moves, and we don't also move all older versions of the page, we should probably apply a canonicalId or canonicalUrl to the older versions.

What do you think about this as a practice? And how do you think it would be best to track it/remember to do it?

[akeller]

From a hygiene and cleanliness factor, I think this practice makes sense. We need to care a lot about SEO, and information about canonicals supports that. Would this be entirely manual to add canonicals to all the pages coming up as WARN(canonicals)? Would it make sense to add this info for all pages?

[christinaausley]

we should probably apply a canonicalId or canonicalUrl to the older versions

Can you give me an example of what this might look like? I can keep an eye out for this and adjust in relevant PRs (one example here), but also happy to set aside an hour every month to take a look at this if we're looking for a maintainer 👍

[pepopowitz]

I'm not exactly sure if I'm answering your questions directly, @akeller:

Would this be entirely manual to add canonicals to all the pages coming up as WARN(canonicals)?

In any given PR, there is not currently a way to identify WARN(canonicals) messages for only files affected by the PR -- the warnings appear for every doc in the entire repo for which a document does not exist at the same path in the "current" version. As of right now, any work we do to add canonicals to all the existing pages coming up as WARN(canonicals) would be completely manual.

As of right now, any work we do to add canonicals to docs moved within a PR would also be completely manual.

My question above is in regards to setting a practice of updating this second set of docs -- taking care of "new" issues as they occur.

Would it make sense to add this info for all pages?

Long-term, yes, I think it makes sense to add canonicals to every page that moves in newer versions.

[pepopowitz]

we should probably apply a canonicalId or canonicalUrl to the older versions

Can you give me an example of what this might look like? I can keep an eye out for this and adjust in relevant PRs (one example here), but also happy to set aside an hour every month to take a look at this if we're looking for a maintainer 👍

This is described in our moving content guide. We have an example in the 8.1 site, though it is using a fully-qualified URL because it crosses over to the supported docs.

[akeller]

In the spirit of iterations and small scopes, can we chunk this down and make incremental progress?

We don't seem to be moving as much content around these days, but I imagine with newly onboarded tech writers we may see some consolidation and restructuring.