Add context on why workaround is necessary

website/build-versions.sh

@@ -50,6 +50,21 @@ function createVersionedDocs() (
   mkdir -p $currentWebsite/versioned_docs
 
   # Workaround for broken links in versions 4.4.0 and before
+  # This is necessarcy because the way legacy versions of the documentation are built
+  # follows these rough steps:
+  #
+  # 1. Check out the version of the stratos repo that you are trying to build documentation for
+  # 2. Build the documentation with that versions revision of the website
+  # 3. Copy the resulting markdown and sidebar files to a version specific build directory
+  #
+  # This means that when we built documentation up to and including v4.4.0, we are using old versions
+  # of docusaurus, but those built documentation files are then included in the documentation
+  # generated by the current version of docusaurus.
+  # In essence, that means we have to apply the version specific workarounds every time we build
+  # the documentation.
+  # Ideally, we would change this such that versioned documentation is built on release, checked in
+  # as an artifact that can be modified later to accomodate changes to make it compatible with 
+  # newer docusaurus (or whatever else) versions we upgrade to.
   printf '%s\n%s\n' "$target_version" "$version" | sort -V | head -n1
   if [[ $? -eq 0 ]]; then
       logInner "Version is 4.4.0 or less, applying workaround for broken links and v3 upgrade"