Configure multi-instance versioning

[pepopowitz]

Epic: https://github.com/camunda/product-hub/issues/231
Prerequisite: #1115

Optimize versions are different than the versions of the other Camunda components. Docusaurus recommends using multiple instances of the docs plugin to enable users to see different versions for different docs.

Work to be done

Preparation (ahead of time)

• Investigate ways to reduce friction in cross-plugin markdown links #1167 (done in feat: MDX plugin to interpret link target URLs based on source file directory #1170)
• chore: remove vNext and optimize docs from sitemap temporarily #1193

Move docs over

1. ✅ Create a "next" Optimize version

   1. ✅ feat: set up optimize docs instance and move one doc over #1166
      This moves a single doc into the new instance, including all configuration necessary to iteratively move more docs over afterward:
      • Add a second Optimize instance of the docs plugin
      • Add a second Optimize set of sidebars for the new instance.
      • Configure sidebars for consistent cross-plugin navigation
      • Move one doc (what-is-optimize) into new instance
      • Update links in documentation for the moved doc (and docs that reference it)
   2. ✅ Iteratively move remaining "next" Optimize docs over: feat: move "next" optimize docs into new optimize instance (subset #1) #1204 and feat: move remaining "next" optimize docs into new optimize instance (subset #2) #1214

2. ✅ Create a "3.8.0" Optimize version

   1. ✅ feat: Extract Optimize v3.8.0 docs to new /optimize section #1234
      This will be merged into main all at once, because this is the current version of documentation and we will confuse people if we release it in pieces.
      • Configure the 3.8.0 version of Optimize documentation
      • Customize NavbarItem so that the version dropdown shows the correct versions, based on which docs are being viewed (in feat: show correct versions in navbar based on which docs you're viewing #1235)
      • Extract everything from docs/8.0/components/optimize to optimize/3.8.0 (in feat (optimize/3.8.0): move content from docs/8.0 to optimize/3.8.0 #1236)
      • Add rewrite rules for optimize/3.8.0 docs (in feat (optimize/3.8.0): redirect rules for optimize/3.8.0 docs #1238)
      • Revert chore: remove vNext and optimize docs from sitemap temporarily #1193 (because we want these things in the sitemap now) (in chore (optimize/3.8.0): revert "remove vNext and optimize docs from sitemap" #1239)

3. ✅ chore: move exisiting Optimize docs into a components/ folder to make space for apis-clients/ and self-managed/ #1286
   For consistency with the new folders planned to move, we'll want to move all the existing Optimize docs into a /components/ folder.

   1. Move /optimize/* into /optimize/components/* for vNext
   2. Move /optimize_versioned_docs/version-3.8.0/* into /optimize_versioned_docs/version-3.8.0/* for v3.8.0

4. ✅ Move Optimize docs from apis-clients & self-managed sections into Optimize instance

   1. ✅ vNext: feat: move next/apis-clients/optimize-api and next/self-managed/optimize-deployment into optimize instance #1293
      1. Move /docs/apis-clients/optimize-api/ docs into vNext
      2. Move /docs/self-managed/optimize-deployment/ docs into vNext
   2. ✅ v3.8.0: feat move 3.8.0/apis-clients/optimize-api and 3.8.0/self-managed/optimize-deployment into optimize instance #1300
      1. Move /docs/apis-clients/optimize-api/ docs into 3.8.0
      2. Move /docs/self-managed/optimize-deployment/ docs into 3.8.0

5. ✅ Update release-procedure.md #1217

6. ✅ Create a "3.7.0" Optimize version

   • ✅ feat: extract Optimize v3.7.0 docs for Components & Self Managed sections #1408

Follow-ups/polish

• ✅ feat(docs): describe multi-instance docs in howto #1313
• bug: non-Next versions of Optimize documentation link to incorrect version of main docs in header #1333
• Make the "Components" item in the top nav active when in the Optimize docs
• Make footer links include cross-instance docs ($docs$ skips over $optimize$ pages, and vice versa)
• Sidebars are difficult to keep synchronized #1396

POC

See #906 for a POC of this work.

Decision to make

What do we want to use as the root directory for the new section of documentation?

In #906, I used optimize as the root. It’s arbitrary, and we can choose whatever we want (except for something starting with docs since that is the main docs instance). (Update: we chose optimize.)

Background

This is Recommendation #1 in the Optimize Multi-Instance Documentation Proposal.

[akeller]

@pepopowitz wants a post mortem for this, and I 100% agree.

[pepopowitz]

@pepopowitz wants a post mortem for this, and I 100% agree.

Added to our 1:1 board 😅

[akeller]

@pepopowitz what work remains open that must be completed for this issue? I know other items have popped up but they seem outside of the scope of this epic.

(More context: I'm interested in pivoting our focus to the C7 SEO issues.)

[pepopowitz]

this is the last bit I consider part of the original work!

[pepopowitz]

Wait, nevermind -- I was struggling to find the Optimize apis-clients docs for 1.3....and it turns out it's because they don't exist.

So

THIS

IS

DONE!!!

[pepopowitz]

Before I close it -- how much do we care about these 2 issues? Are they worth creating issues for?

• Make the "Components" item in the top nav active when in the Optimize docs
• Make footer links include cross-instance docs ($docs$ skips over $optimize$ pages, and vice versa)

[akeller]

I think we can leave them here for context, no need to create new issues at this time.

I'm excited to celebrate all your great work with this 🎉

[pepopowitz]

👍

CLOSING AS COMPLETED