Docs strategy purposal

[nunix]

Currently, the Elemental docs are hosted in the same repository than the Elemental code, and the same goes for Elemental-toolkit.

After the migration of the Elemental docs to Docusaurus, there's now few topics that should be clarified:

• Both docs have a different layout and theme -> this brings some confusion to our users
• The docs are in two repos, with two different frameworks which makes it more confusing for our contributors
• Docusaurus uses nodejs, same as Cypress, and now the package.json file is a mix of dependencies from both applications -> this causes some side effects on one or other application
• The Netlify preview also impacts all the PRs from the Elemental repo, instead of only the docs ones

In order to address the points above, a possible solution would be to have a new repo, containing both Elemental and Elemental-toolkit docs. The framework would be Docusaurus, which will allow us to "split" the browsing menus depending on which project documentation the users and contributors want to read/contribute.

Concerning the URL, a team decision should be reached. Currently, Elemental doesn't have a top-level domain. So we could have the following solutions:

• Reuse the existing URL of Elemental docs (rancher.github.io/elemental) -> the site deployment would be migrated from the current repo to the new one
• Create a new URL based on rancher.com, as this is required for other Rancher projects and SEO optimization: i.e. docs.elemental.rancher.com

Here's a quick overview of how the new solution would look like:

• Repo: rancher/elemental-docs
• URL: rancher.github.io/elemental OR docs.elemental.rancher.com
• Framework: Docusaurus
• Docs hierarchy:
  • /docs: contains the Elemental docs
  • /docs/toolkit: contains the Elemental toolkit docs
• Browsing:
  

Finally, if the strategy above is agreed, the implementation would be done in two major phases:

• First phase: migrate Elemental docs to the new repo, setup the github pages deployment and setup the URL and Netlify preview
• Second phase: migrate the Elemental Toolkit docs and add a redirection from the current docs site to the new (the URL has already been shared on the SUSE Edge 2.0 communication)

Let me know what you think about and, of course, if there's another solution that you might think could work too.

[nunix]

After discussing the purposal with the team, we reached an agreement on moving the docs to its own repo.
Here are the tasks for the migration:

• Create new repo - i.e. rancher/elemental-docs
• Move rancher/elemental/docs and Docusaurus configuration to rancher/elemental-docs
• Setup new domain name - i.e. docs.elemental.rancher.io (same as Rancher Desktop docs)
• Add redirection from current docs site (rancher.github.io/elemental) to the new domain name
• Enable Netlify PR preview
• move rancher/elemental-toolkit/docs to rancher/elemental-docs
• replace https://rancher.github.io/elemental-toolkit with a redirect

After few weeks/1 month, the redirection can be removed as well as the docs directory on the rancher/elemental repo.

[kkaempf]

There's more

• move rancher/elemental-toolkit/docs to rancher/elemental-docs
• replace https://rancher.github.io/elemental-toolkit with a redirect

[nunix]

edited the message and added the two points. Thanks @kkaempf for the feedback.