Website management concerns

[pgrange]

In a perfect world, the website workflow would be transparent but it has consumed time lately. I can see the following issues:

• Building the website is super slow:
  • 23’ on master
  • 5’ on branches
  • 5’ to 10’ more minute for the actual publication
• Current version management process:
  • Need to push to release or won’t publish the stable version
  • Need to build doc twice to have the monthly available for master in / and /unstable (lost the knowledge and broke the build)
  • Need to know the URL /unstable to find the doc (minor)
• Docusaurus is too smart for me:
  • Need to reload the monthly to see May appear (only April otherwise)
  • SN spotted some subtle errors with pictures https://github.com/facebook/docusaurus/issues/9036
  • Had to code an ad-hoc react component to manage versions in docusaurus
  • Have to include an ad-hoc react component to display the API documentation
  • Can not use docusaurus version system for
  • Haddock
  • API
• Can not see the website for each branches
  • Makes collaboration with non/less technical people complicated on docs

Expected:

• building and publishing the website is fast (less than 5')
• accessing the various versions of the docs is obvious for visitors
• we can see a preview of the website on any branch without needing a local dev environment

[ch1bo]

Ideas:

• Build time

  • separate website building from CI to get faster feedback
  • not build all the translations for a basic check (CI)
  • only build the website once with all translations and versions in there (to publish)

• Maybe we have multiple websites?

  • technical artifacts like benchmarks and api docs
  • instructions which are related to the software, but not as often changing
  • content just getting published like the monthly reports

[ch1bo]

958 Should improve on the build time by doing the build time ideas above

[ch1bo]

From @abailly-iohk: In the diataxis framework terminology, generated stuff like the benchmark results would be reference and perhaps they should have their own dedicated (sub-)site?