docs: Review documentation site generation for versioned OPA docs

[charlieegan3]

Currently we use Hugo to build a website for OPA's homepage and documentation content. There are some sharp edges in this setup:

• developers must use a compatible Hugo version, 0.113.0. It's not currently possible for us to upgrade without updating the old content due to the use of a front matter field.
• there are two content dirs, one containing the regular Hugo content under website and another containing the current docs content. Running generation scripts is required to be able to build a local version of the site for testing docs changes.
• Versioned docs are generated by copying the docs content from all versions into a generated content dir under docs. This generates paths the like /docs/v0.67.1/. The challenge that this poses is that content from past versions of OPA must work with the current Hugo site and configuration. This is something which, if broken, is only spotted after merging to main when all the contents is updated.

These issues make it hard to maintain the docs, and, I feel, place the bar to drive by docs contributions too high.

I think we should consider a system where:

• all content from all versions is easily available when developing the site, rather than needing to run lots of generation scripts and pull state from git.
• Use a static site generator which has native versioned docs support.
• Review the content where versioning is important, the note from https://docusaurus.io/docs/versioning is interesting:

Most of the time, you don't need versioning as it will just increase your build time, and introduce complexity to your codebase. Versioning is best suited for websites with high-traffic and rapid changes to documentation between versions. If your documentation rarely changes, don't add versioning to your documentation.

What if we only versioned a limited set of pages, for example:

• https://www.openpolicyagent.org/docs/latest/policy-reference/
• https://www.openpolicyagent.org/docs/latest/rest-api/
• https://www.openpolicyagent.org/docs/latest/cli/

[srenatus]

Sorry you ran into this problem: the website build only doing the latest version was intentionally done for dev and preview (https://github.com/open-policy-agent/opa/issues/4379) because it took so long to always build everything. As a workaround, when doing "global changes" that need the previous versions, I've tended to revert this Makefile change, which would make netlify build everything for a preview.

Taking a step back as suggested, I think the versioning isn't needed, or it's even harmful. Besides complicating the build process (since Hugo wasn't made for this), it also makes people find old content, use old images, etc.

Where it is important is when it comes to builtins and when they've been introduced -- but we already have introduced those version tags:

What if we only versioned a limited set of pages, for example:

• https://www.openpolicyagent.org/docs/latest/policy-reference/
• https://www.openpolicyagent.org/docs/latest/rest-api/
• https://www.openpolicyagent.org/docs/latest/cli/

What if we didn't? 😅 The policy reference hasn't changed much since "every". There's going to be a v1 release eventually and we will stop pretending that "in", "every", "contains" are optional future stuff -- it's just Rego.

The REST API hasn't changed at all, I think, in the last years.

The CLI changes are usually minimal, but it would help if you had a chance to figure out when a flag was introduced -- but really, I think the scenario is like this:

1. you find a flag in some docs
2. you try it locally, it's not found
3. you try to figure out if it's in the latest version

Right now, there's no easy way to figure out when a flag was introduced. You'll have to flip through all the versioned docs...

tl;dr: I think our current approach to versioning docs is rather blunt and worth revisiting. I've never referred to anything but the "latest" docs (and maybe "edge"), and wouldn't shed a single tear if they went away.

[charlieegan3]

What if we didn't?

I mean, the thought had crossed my mind! 😅

I suppose the other way of thinking about it is that OPA is a more simple component to deploy and update than say, Kubernetes. Kubernetes have a year support period for releases: https://kubernetes.io/releases/patch-releases/#support-period, and various managed offerings have a range of active versions exposed to users via channels.

In OPA we don't really operate releases in the same way and so even though the usage of dated OPA versions is high, it's less important that the docs are timecapsuled for every version for the reasons that Stephan outlines above.

[stale[bot]]

This issue has been automatically marked as inactive because it has not had any activity in the last 30 days. Although currently inactive, the issue could still be considered and actively worked on in the future. More details about the use-case this issue attempts to address, the value provided by completing it or possible solutions to resolve it would help to prioritize the issue.