Guide website revamp

[thibaudcolas]

The guide website is showing its age, there are a number of tech debt issues that have been accumulating and even if they were all addressed there are a few aspects of the setup that I think warrant a rethink. Could use feedback!

Translations

We just don’t have the resources currently to translate the site. We need to overhaul how this is set up so it’s more realistic for the site to be multilingual. This can mean switching over to automated translations with manual review (#273), or making improvements to wagtail-localize (#269), or redesigning the site so it would work better with only some of the pages translated (could have a standalone guide page per language rather than expecting 1:1 translations).

As-is, this issue manifests itself with a combined version + language switcher where almost none of the languages are actually relevant.

Versioning

Turns out over time versions accumulate, and over three years of the site’s existence we’re now at 12 versions! This works pretty well but along the way I’ve noted a few things that make our current approach cumbersome:

• Some parts of the site don’t need versioning. In particular Releases, About, Contributing, and the homepage. As-is, it’s not possible to skip versioning for those pages.
• Most pages really don’t change that much between versions. For most content we would be fine with a "changed in Wagtail x.y" note
• There’s no system in place to unpublish versions.
• Versioning screenshots of the UI is tricky, requiring multiple copies of the images which are hard to maintain

This plus translations issues surfaces again in the combined version + translation switcher which has become very unwieldy.

Other

Misc other issues that get in the way of updating the site’s content and opening up access to others:

• Upgrade guide website to latest Wagtail LTS #402
• Changing a page slug creates a redirect with the wrong language code (/en/ rather than /en-latest/) #359
• Portuguese (Brazil) References page: runtime error #317
• Spike: deep copy of page tree including assets #72
• "Live" page links within the CMS use the wrong locale #276
• Frequent timeouts when doing bulk actions related to translations

---

Structure overhaul

All of the above makes me think it’s time for a rethink? I see three options, from most complex to simplest:

• Update wagtail-localize or Wagtail itself to have support for other dimensions than "locale". That way the site could have its pages along two dimensions, locale and version. Still the same complexity but easier to maintain / support if it’s not just a hack on the one site.
• Switch to vanilla translations with locales only, with versions becoming sub-sections of the content.
• Switch to vanilla translations with locales only, with versioned content moved as a series of "upgrade notes" within the one page.

I’m leaning towards that last simplest option, as I expect we make UI changes incrementally enough in the CMS that we could draft content (and pick images) that convey the last two years’ worth of upgrades clearly enough. Those "new/changed in version X" disclaimers could also be managed via StreamField blocks metadata and image metadata.

I expect for translations in particular, if we kept the 1:1 model, it’d be dramatically simpler to only have to worry about translating one page and keeping it up-to-date, rather than one page across multiple versions.

[lb-]

Would there be any way to tag a Page version against a Page revision?

Here's my thinking, we go with simpler locales (vanilla translations with locales only). Then when we get enough changes to publish a revision, the workflow system adds an extra field for Wagtail version.

This version, if updated from previous revisions, triggers a static build of the INNER content of that page. It could then be made available within each public facing page as a dropdown (url param, not path) to allow to view previous versions of that page.

A similar dropdown/option could exist like we have today, but the mechanics of how previous versions are loaded would work differently.

Instead of opt-in for a NEW release, we opt-in for storing a revision at a past release.

The assumption is that MOST users would want the new version of content and most of the time that's what's available. We can still link to / show old content though if needed.

Just an idea.

[thibaudcolas]

@lb- I’m skeptical of options like this that require customizations to Wagtail’s internals. If that kind of capability was present in Wagtail itself maybe, otherwise I think the simpler / vanilla this site is the better.

[lb-]

I was thinking of using RoutableMixin and the documented approach to allow for custom workflow models.

But haven't really dug further into a poc.