Improve documentation versioning

[imiric]

The current way of documenting specific k6 versions (introduced in #283) has some drawbacks and limitations:

• The process involves duplicating the entire javascript api tree, which is inefficient and bloats the repository, but more importantly carries layout and content changes that need to be repeated on all versions to be consistent.
  If you take a look at the landing page for the latest v0.42.0 version, you'll see that the "Init context" explanation is different from v0.40.0 and earlier. If we need to make layout or style changes, it needs to be done on all versioned copies.

• It only versions JS API docs. Sometimes we make changes to k6 options, but there's no way for the user to see which version is documented. So we resort to phrases like "New since v...", which often goes stale, and is not relevant after those versions are widely deployed. See the discussion in Add documentation for new wildcard Hosts feature #965 (comment).

• It doesn't version any of the extension docs. xk6-browser and xk6-disruptor are stuck with "latest". This documentation shouldn't be only under the "JavaScript API" section, since it has an introduction, installation, "Getting started" guides, etc., but maybe that's a separate issue.

I don't have a specific proposal for fixing this, but I'm happy to brainstorm some solutions with the PixelPoint team.

Related issues: #675, #955

[ppcano]

you'll see that the "Init context" explanation is different from v0.40.0 and earlier. If we need to make layout or style changes, it needs to be done on all versioned copies.

Why? I am not sure this is a must. My approach is to fix the latest version and the old ones are unmaintained (saved for reference).

So we resort to phrases like "New since v...", which often goes stale

Agree. We should do better on updating these notes.

After how many new versions should we drop the version note? 2, 4, 6, 8?

It doesn't version any of the extension docs. xk6-browser and xk6-disruptor are stuck with "latest".

Agree. This has been considered internally but not prioritized.

[imiric]

Why? I am not sure this is a must. My approach is to fix the latest version and the old ones are unmaintained (saved for reference).

Sure, that makes sense for some content, like API documentation, which is historical. In the init context example, nothing really changed from one version to the next; we just decided to update how that concept is explained. In that case, the updated explanation would benefit all versions of the docs.

But more importantly, how would this work with layout or style changes? Say we want to change the API docs layout to not use tables anymore. We would have to manually change each version, and the effort to do that would be multiplied for each version we maintain. Or we can let it be and have the site looking differently for each version, which is not ideal. The CSS maintenance alone would be a nightmare, as designers would have to make sure that layouts of all versions are styled correctly.

This is why it's a problem to just copy entire directory trees. We need a more sophisticated templating system that can separate the versioned content from the layout/style and other non-versioned content. Maybe we can first research how other docs systems handle this.

After how many new versions should we drop the version note? 2, 4, 6, 8?

I think 2-3 versions feels like sufficiently "new" where it's useful to point this out. It should preferably be done with a dynamic component that can determine which version is shown, and how far it is from the latest version, and decide whether to show this "New since" label or not.

[ppcano]

But more importantly, how would this work with layout or style changes? Say we want to change the API docs layout to not use tables anymore. We would have to manually change each version, and the effort to do that would be multiplied for each version we maintain. Or we can let it be and have the site looking differently for each version, which is not ideal. The CSS maintenance alone would be a nightmare, as designers would have to make sure that layouts of all versions are styled correctly.

• to not use tables anymore.
• the site looking differently for each version
• CSS maintenance alone would be a nightmare

I think this is not a current problem, as none has requested these new capabilities.

If any of these needs arise, then we'll figure it out. Until then, IMO, they'd be premature optimizations.

---

2-3 versions feels like sufficiently

I think we want the documentation show the latest 4 version. For simplicity, we could follow the same number of version to drop version notes.

[heitortsergent]

Closing this since we've moved the docs to Grafana.