[SITE][FEATURE] Need a away to version documentation

[amznestebanpapp]

Describe the feature you'd like available on the website

Currently we don't have a good way to document a feature that is not available in other versions. Suppose a new feature is introduced in development, a user on a particular release (e.g. 21.11.1) reading the documentation may read about the feature, but the feature is not available in that release. This can create confusion. For a developer, its also hard to figure out when to introduce the documentation. Developers usually do one of the following options:

1. do not document until close to release, that has less impact to customers using a released version. But wont give visibility of the feature to users using development. It's also prone to "forgetting to add the documentation"
2. flag the feature somehow, like "Available in future release", however, that makes it harder because now we have to track in which version each feature is available and when to remove the flag or how long to keep it.
3. document it, users run into not finding the feature, they log bugs/ask in discord, etc

Proposed implementation

A solution that seems to be common among sites is to present an option to choose the documentation version the user wants to use. Then the documentation site adjusts to such version. Some examples: CMake: Read the docs:

I would expect to put the documentation for the feature into a development branch in the o3de.org repo around the same time that is developed. Then users of o3de.org select "development" and see the feature's documentation (docs would likely be a bit behind). If they select "21.11.1" they don't see it. Once development is branched into a new stabilization, I would expect the same to happen to documentation. Once stabilization is made into a release, I would expect the same to happen to documentation. Of course, documentation is usually behind, so at those branch points there may be docs that need to be merged into different branches.

I understand there may be practical limitations, tools and/or features that need to be worked on with the current doc framework.

This is my understanding of the current issues:

1. The way that the web generates is that it generates a "static webpage", so we would need to duplicate the webpage per release. Main issue there are resources, I don't know if it can be handled, but duplicating resources would take a lot of space. I would expect some way to deduplicate resources and make all the html point to the same resources (something similar to a git lfs mechanism where the link is the hash of the content and all the content is in one location). But I don't know much of the framework being used to see if that is possible.
   • When I brought this in sig-docs-community, there was a claim that its really hard to maintain branches on documentation, that merging doesn't work that well because English doesn't merge... I don't have the experience to suggest solutions to that, I would expect that to merge, its a text file. Yes, sometimes a merge will be non-trivial and would require rewording, but so does code or any text-based merge (e.g. merging json sometimes requires adjusting commas, brackets, etc). I understand sometimes some fixes in documentation in e.g. stabilization will require some rewrite in e.g. development if major changes have been done there. But this, same as source code, is an infrequent case.
   • there is no clear definition how often we will release and what releases/versions we want to document. IMO, we should version the "main" branches we have in o3de: development, stabilization branches, releases (e.g. 21.11.1, etc). That would make documenting a new feature to flow together in the same branches in the o3de.org repo as it does in the o3de repo.
   • from the UX point of view, I would expect some "selector" like the examples from above.
   • one last concern was the versioning of videos/screen captures/etc. They don't need to get updated in each release. Sometimes a video tutorial will be out of date for a long time until a new one is created. That can be flagged in the video itself or as a footnote (e.g. video made with version X). Once a new video/resource is created, it can replace it from that version forward.

Available alternatives

A suggested alternative is to flag things and state in which version they become available. This IMO is harder to achieve and maintain. A feature is usually done in the development branch. It could take months for that feature to become part of a release. We currently name releases based on the month the release happens, so it would be problematic to predict what the next release will be and mark the documentation accordingly. This IMO is also really hard to read. In the cases where I have seen documents written this way (e.g. Microsoft documentation), it makes it really hard to understand which versions it applies to. Sometimes it ends up a mix with "sections" stating the differences between versions and/or making the whole page state something like "Applies to version X". Microsoft also has the approach to not deprecate things, which is not our case. In our case we may have a feature that starts one way and changes to something else and ends up being something completely different. Documenting that in one page, with the different options will not only be extremely hard for the person writing the documentation, it will make it really hard to read.

[amznestebanpapp]

Took a look at the size issue, it seems the o3de.org repo has a "static" folder with doxygen-generated documentation. That documentation has a lot of duplicated files, e.g. jquery.js takes 171Kb and its there 91 times.