[Doc] Clarify the relation between supported Pulsar versions and versioned docs

[visortelle]

Search before asking

• I searched in the issues and found nothing similar.

What issue do you find in Pulsar docs?

The release policy page states that Pulsar has two supported versions on the current date.

https://pulsar.apache.org/contribute/release-policy/#supported-versions

The documentation site provides four versions to choose from in the dropdown list:

This document describes that versioned docs also should be updated: https://pulsar.apache.org/contribute/document-contribution/#update-versioned-docs.

The "If you want to update versioned docs" statement is a bit vague. Let's say I found a mistake in the latest Pulsar version docs and want to fix it because I use this version. But I don't care about older versions. Therefore I "don't want" to update old versions, although probably should.

Also, this document doesn't clarify which versions should be updated - listed as actively supported on the release policy page or listed in the dropdown.

If some of them aren't actively supported, should they also be updated?

For example, Kubernetes maintains only the newest versions, although it's a cheat because they don't have an LTS version.

Maybe it also makes sense to maintain only versions that have the Active Support status, and for others to show a similar banner:

After figuring it out, I plan to update the page that describes the versioned docs update process a add it to the PULL_REQUEST_TEMPLATE.md checklist. Now the need to update versioned docs may be not clear for new contributors.

What is your suggestion?

Any reference?

No response

Are you willing to submit a PR?

• I'm willing to submit a PR!

[visortelle]

Idea: don't require updating versioned docs from contributors.

Making a small documentation fix in a single place is easy, but if we ask contributors to fix it in 5-10 places, it may prevent the initiative at all.

It could increase the amount of contributions to the documentation.

I'm not sure how to better organize this process. Who should do this job - the PR reviewer or someone else like a technical writer?

[visortelle]

Discussed here: https://lists.apache.org/thread/jh89gx0om6vf4dvxqhgx59gf3m8vc2fv
The PR is merged: apache/pulsar-site#843