hydra
hydra copied to clipboard
Published
20 hours ago •
input-output-hk
input-output-hk
Website management concerns
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
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
