Create versonised forwarders to documentation

[YetAnotherGerrit]

Create a system that allows documentation be called with a version number (e.g. 6.4.1) that forwards directly to the most fitting (of the available) documentation.

Use-Case

As a Zammad-developer I want to place links to documentation inside Zammad that always link to the correct documentation.

As a SaaS-customer that uses a pre-release-version of Zammad I want to be forwarded to the pre-release documentation when I click a documentation-link.
As a documentation-host I want to change the redirect on release-day from "next.zammad.org" to "www.zammad.org".

Acceptance criteria

• Should work for old/new documentation/tech-stack.

[ralf401]

Thanks for the suggestion. However, I would argue against version numbers because:

• We (@dvuckovic, @mgruner, me) decided against it to keep it lean, reduce maintenance effort and have it in a modern way like many other documentations
• Developers should always point to the main/master/stable (name not yet defined for the new documentation), because we want readers to be on a current version. For those who decide to use Zammad in develop flavor, they are probably aware about that fact and can manually switch to the next.zammad.org.
• For the system docs we had only pre-release and main so far and it seems that this was fine.
• Specific stuff (e.g. history of ES- & Zammad versions) can be included in the content, if needed.
• If it is possible and realistic that different versions of Zammad include links to different versions, the situation is different and this could be a useful suggestion

=> So the only use case in my eyes is a reader which is on an old version of Zammad and sees no new features. And this is a situation which we don't want and support anyway.

But if you see still a need, I'm open for that. Maybe @mgruner and @dvuckovic can add their point of view if I missed something or am wrong.

[dvuckovic]

I think the proposed versioning of links is not a good idea. I think it would either introduce a significant overhead in form of updating these links for each subsequent release, which is very error prone OR we would need to come up with a very complex redirect system that will need to be kept up-to-date.

Actually, I believe we already have a pretty good system for showing relevant docs to all users, allow me to elaborate.

This system is using an alternative approach, based on redirects. It makes sure the user is always pointed to an existing page in case of unreleased features. Take the M365 Graph channel as an example, available from Zammad 6.5:

• We published the docs for pre-release version at https://admin-docs.zammad.org/en/pre-release/channels/microsoft365-graph/index.html
• We included the link to the docs in the app that points to the future latest version at https://admin-docs.zammad.org/en/latest/channels/microsoft365-graph/index.html
• We added a soft redirect from latest => pre-release, until the release day
• At the day of the release, when latest docs are finally published, the redirect stops working, and the original URL shows new content

We need a similar mechanism for next.zammad.org at some point, but I think we are long way from when we will actually use it (admin interface?). In any case, this is not something that will be needed for the initial switch to www.zammad.org, IMO. And I would have some more ideas there to make sure the linking is even more seamless (e.g. quick named links, similar to tiny URLs).

[YetAnotherGerrit]

Thank you for the input. We should/will have a refinement about that, once it reaches the Focus lane. Maybe we can even use a some kind of short url kind of approach? http://zmd.docs/?version=6.4.1 or something like that?

I will further explain the use case in a refinement and you guys come up with an even better totally different approach to that :-)