Improve the documentation #686
Closed
CodeDoctorDE
started this conversation in
Polls
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
Hello,
The docs are currently unresonable big in the repository. It has many source files (because of docusaurus) and every page is
PageCount * LanguageCount * VersionCount
in there (for every language, for every version). That counts up very high over time.The other problematic is that we have so many languages that docusaurus can't build it (it needs too much ram). Currently, we only show a very small part of the uses languages in there.
We have a few solutions:
Remove versioning
Currently every minor version (
1.0
,1.1
, ...) gets its own documentation. We copy the current nightly changes and version it into this system. That makes the repo very big on every verison.Since there are not much changes, there are many duplicates there.
Additionally, when changing the documentation to add new things to document, we need to change it on every subfolder.
My solution would be to only make a duplication on every major release which isn't planned in the near future.
Use starlight instead
Starlight is a new documentation system build by Astro.
It is very fast (build times in seconds, instead of minutes with docusaurus) and instead of using react, it uses plain javascript or plain html in the build output. You could use mdx (markdown) too here and we don't need to change the markdown too much.
See more here: https://starlight.astro.build/
This also means we need to put work in it and the page will look different.
Your feedback
What do you think? Do you agree removing versioning and do you think the work changing the entire documentation framework is worth the efford?
Feel free to comment here if you have other ideas.
1 vote ·
Beta Was this translation helpful? Give feedback.
All reactions