Optimal approach to versioning of the documentation

[Yash Jipkate]

Hi community,

I am currently planning the migration of the infusion-docs
<https://github.com/fluid-project/infusion-docs> repository. One of the
features that it needs to have is the versioning of the documentation. I am
exploring various approaches to do that and would like to get your feedback
on which should be the best way.

There was initially the idea to pull the different versions from the tag
zips and the branches into the *content/* but since they would contain the
SSG code too and that would be a waste. But I am open to this method too if
the others seem less optimal. But in my opinion (and Justin's), this
approach should work better when the contents are separated from the SSG
code.

One proposal is to make the versions into subdirectories of the
*contents/* folder
where the older versions reside in the subdirectories and the latest
version resides in its root. This way we can refer to the versions by
appending the URL with the version. This also enables us to edit the
content in the older documentation if need be.
The main drawback of this approach is the duplication that it results in.
The subdirectories will have all the contents of the version. So even if
there are minor versions the approach will copy the whole content to the
subdirectory. There is also an overhead of manually making the release
subdirectories.

Another approach is to host the different versions on different subdomains
as is the method used by 11ty, Angular, and React for their versioning. It
is not clear how they use dynamic subdomains (or do they even use it or do
they manually deploy the subdomains) but this can reduce the duplications
since the different versions would be present in the different branches
that would be hosted.

Although these problems persist in the intermediate time until the contents
and the SSG code are separated but the user and developer experience
shouldn't be compromised at any time.

I would like to get some feedback from the community on what should be the
best way forward or any other approach that needs to be discussed. Please
feel free to ask if you need some more clarification.

Thanks
Yash

-- 
Yash Jipkate
Sophomore Undergraduate,
IIT(BHU) Varanasi
India
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.idrc.ocad.ca/pipermail/fluid-work/attachments/20200527/25267c07/attachment.htm>