docs: improve the documentation

[dcoa]

This PR improves the repository documentation for a better understanding of the eox-tenant plugin.

For the plugin description

Plugin for managing multiple tenants (organizations) within a single Open edX instance, replacing the microsites and site configuration features with a more robust multi-tenancy model.

Proposal

➡️ Maintain the settings configuration for the current release.

• Simplification: Find the necessary information without being distracted by details that may no longer be relevant (e.g. Ironwood).
• Relevance: Users typically work with recent versions of software. Documenting the latest settings ensures that our documentation is pertinent and useful for most users.
• Maintenance: We lower the risk of outdated information and reduce the effort required to keep the documentation current. (e.g., before Redwood we have that the current configuration works for Juniper, that is not true because the latest version at that moment doesn't support that release).
• Accuracy: During the migration process, we are adding the name of the previous release in the documentation even when the settings are the same, which could lead to unnecessary action for the user.

Also, the packages management like (pypi or npm - use the readme and the latest release to explain the documentation) if you want to install another version you should select it and that will show you the relevant information for that tag (readme for that version). That behavior is another motivation for this change, showing the information relevant to the version that the user wants to use.

Additional information JIRA

[magajh]

Proposal

➡️ Maintain the settings configuration for the current release.

• Simplification: Find the necessary information without being distracted by details that may no longer be relevant (e.g. Ironwood).
• Relevance: Users typically work with recent versions of software. Documenting the latest settings ensures that our documentation is pertinent and useful for most users.
• Maintenance: We lower the risk of outdated information and reduce the effort required to keep the documentation current. (e.g., before Redwood we have that the current configuration works for Juniper, that is not true because the latest version at that moment doesn't support that release).
• Accuracy: During the migration process, we are adding the name of the previous release in the documentation even when the settings are the same, which could lead to unnecessary action for the user.

Also, the packages management like (pypi or npm - use the readme and the latest release to explain the documentation) if you want to install another version you should select it and that will show you the relevant information for that tag (readme for that version). That behavior is another motivation for this change, showing the information relevant to the version that the user wants to use.

Hi @dcoa,

Thank you for the detailed explanation in the PR description regarding the removal of setting configurations for previous Open edX releases. Your points about simplification, relevance, maintenance, and accuracy are well noted.

However, I have a few thoughts:

1. If we are including an Open edX named version in the compatibility table, I think we should keep documentation of the settings necessary for successfully using this plugin with that version. That's why I'm not entirely convinced about removing all previous settings.

2. If we are going to direct users to check the release notes, we need to ensure we consistently include the setting config for the supported Open edX versions in the release notes of a new eox-core version, or at least when there are breaking changes requiring updates in the configuration for a specific named version. This should be documented in our release strategy

I think it's a good idea to include this information in the release notes from now on. Maybe we could keep the currently listed settings configurations in a document on RTD and just provide a link to it in this README so users can check it if needed?

[Alec4r]

Proposal ➡️ Maintain the settings configuration for the current release.

• Simplification: Find the necessary information without being distracted by details that may no longer be relevant (e.g. Ironwood).
• Relevance: Users typically work with recent versions of software. Documenting the latest settings ensures that our documentation is pertinent and useful for most users.
• Maintenance: We lower the risk of outdated information and reduce the effort required to keep the documentation current. (e.g., before Redwood we have that the current configuration works for Juniper, that is not true because the latest version at that moment doesn't support that release).
• Accuracy: During the migration process, we are adding the name of the previous release in the documentation even when the settings are the same, which could lead to unnecessary action for the user.

Also, the packages management like (pypi or npm - use the readme and the latest release to explain the documentation) if you want to install another version you should select it and that will show you the relevant information for that tag (readme for that version). That behavior is another motivation for this change, showing the information relevant to the version that the user wants to use.

Hi @dcoa,

Thank you for the detailed explanation in the PR description regarding the removal of setting configurations for previous Open edX releases. Your points about simplification, relevance, maintenance, and accuracy are well noted.

However, I have a few thoughts:

1. If we are including an Open edX named version in the compatibility table, I think we should keep documentation of the settings necessary for successfully using this plugin with that version. That's why I'm not entirely convinced about removing all previous settings.

2. If we are going to direct users to check the release notes, we need to ensure we consistently include the setting config for the supported Open edX versions in the release notes of a new eox-core version, or at least when there are breaking changes requiring updates in the configuration for a specific named version. This should be documented in our [release strategy](https://github.com/eduNEXT/edunext-internal-documentation/pull/194)

I think it's a good idea to include this information in the release notes from now on. Maybe we could keep the currently listed settings configurations in a document on RTD and just provide a link to it in this README so users can check it if needed?

Hi,

I have been thinking about just adding the link to the tag/documentation should be enough: e.g: https://github.com/eduNEXT/eox-tenant/blob/v6.2.0/README.rst, at least for releases that are not compatible with the current version.

Because if the table show that nutmeg is compatible with versions greater than or equal to 6.2, it means the latest version 11.7.0 is compatible also.

Its assumed that a version is compatible by default if the user doesn't have to change any setting, if the user has to do something, we should add it to our docs.

However, remember that we have "contract" to support the previous release and current release, if a release is 2 version before the current, we could try but is not mandatory.

[dcoa]

To clarify, I will use “version” to talk about eox-tenant and release to refer to Open edX.

I'm not 100% sure if I caught your concerns but those are my thoughts:

@Alec4r, the contract is still maintained, this repository is a good example of it, the changes for Maple, which is the oldest release supported for 11.x, are listed. Nutmeg, Palm, and Olive are not listed because they use the same configuration as Quince does.

I was thinking of the major release (for the settings list), and the paragraph description does not explain that, sorry for that.

Maybe we could keep the currently listed settings configurations in a document on RTD and just provide a link to it in this README so users can check it if needed?

@magajh, I'm not against this idea, even at some point we have to do that because of the length that section would have in the future.

The compatibility notes table should exist as it is because that gives us an idea of which version to install for each Open edX release, we agree about that. However, from my point of view ,the usage section should describe the information for the eox-tenant version that is displayed. If the user wants to use version 6.x, they can visit that tag and the readme gives the corresponding settings.

Let's use Django documentation as an example, when you open it, the latest release (5.0) is displayed if you are using a previous one, you should select the version, that changes the documentation. (I think is the same but inside GitHub).

Of course, the most important here is to have documentation useful for anyone and you have a better understanding of what is necessary, I'm open to making any relevant changes. 😁