Replies: 7 comments 8 replies
-
January 9 2026 Docs Kickoff CallToday we had a brief (45 minute) virtual meeting to discuss the status of the site, where we saw problems and what our initial focus might be. The very rough agenda of topics we started with was:
As a starting focus, the meeting attendees agreed on the following areas to begin work on: Multiversion: add key kubestellar docs1.b The versions with highest priority to add to the new docs are unreleased-development (from the main branch) and release-0.29.0 (aka latest). The current website docs are based on 0.29.0 but are not fully up-to-date. Document Nextra navigation process3.a Understanding and documenting how the website navigation is generated by Nextra to ease future development Additional items3.b Examining/experimenting with file trees of MDX files... @KPRoche will do some experimentation when he returns later in January There was also some consensus that Slack discussions of the site and documentation content would best take place in the more general kubestellar-dev channel while Nextra-specific tweaks and maintenance go in the private kubestellar-docs channel. Useful reference linksThe active Nextra based site is at https://kubestellar.io |
Beta Was this translation helpful? Give feedback.
-
Considering Website/docs layout (topic 2)(Pulling this into a separate comment so it can have its own thread) During the meeting I suggested this sort of structure for the documentation site in general. (This is painted with a broad brush, not intended as an exact map.)
This is a very crude map, but as I am traveling soon I wanted to record it here before I go offline. |
Beta Was this translation helpful? Give feedback.
-
|
I am not sure whether or where this fits into the existing taxonomy, but I think that there should be some basic principles about how things hang together. Following is what I suggest.
|
Beta Was this translation helpful? Give feedback.
-
|
Regarding item 2, there is content from the mkdocs site that got lost in creating the new site. In particular, https://kubestellar.github.io/kubestellar/unreleased-development/contribution-guidelines/contributing-inc/ got lost. You might think that it is at the following page, but (as you can see) that page actually has different content (it is about contributing to the docs, not the lost content).
|
Beta Was this translation helpful? Give feedback.
-
|
#786 |
Beta Was this translation helpful? Give feedback.
-
|
We need to talk about the hierarchy within one version of the documentation. I think this is part of item 2. I have a link to an old design: https://www.figma.com/board/IHLBwlFC6i4Ibh2DVIzBxX/KubeStellar%E2%80%AFv0.27.2-Documentation--UI--and-Design-System-Audit?node-id=235-1320&p=f . That is the latest design document that I have. FYI, the mkdocs site is at https://kubestellar.github.io/kubestellar/unreleased-development/readme/ In that Figma outline, I see More importantly, there is not a single strong clear division between "install" and "use". For a picture, see https://kubestellar.github.io/kubestellar/unreleased-development/direct/user-guide-intro/#the-full-story . KubeStellar is intended to be enterprise software, not demo-ware. Enterprise software needs to fit a variety of use cases. They differ in what is determined and when and by whom. Following are some degrees of variation envisaged.
|
Beta Was this translation helpful? Give feedback.
-
IMPORTANT: Modification coming to kubestellar/kubestellar repository doc filesAfter a small swarm of PRs in the last week to modify the copies of the documentation files remaining in the kubestellar/kubestellar repository, instead of the active version in the kubestellar/docs repository, I am preparing to remove the redundant files from the repo and replace them with a readme saying "edit docs files in the doc repo" I don't want contributors wasting their energy editing the wrong files nor our reviewers time and energy dealing with PRs on the wrong files. |
Beta Was this translation helpful? Give feedback.

Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
Introduction: How we got here and what this discussion board is for.
A huge amount of effort went into the launch of the new Nextra-based kubestellar.io site, first in developing its visual language and components, and then in implementing that new design as an operational website.
Problems with the current version
Like many major projects, the site is exhibiting growing pains.
Most significantly, the original design called for pulling docs files for the individual component repos of the KubeStellar system from those repos dynamically, and rendering that into a unified site. The performance of pulling those files on the fly from GitHub was extremely poor, with some pages taking 30-60 seconds to load.
We therefore pulled copies of the current release documentation into this kubestellar/docs repository and that eased the performance issue, but severed the connection between the original repo docs structure and their representation on the website.
Most significantly, it broke the ability to render multiple versions of the docs for the extant releases of KubeStellar as well as the under-development branch. It also makes it harder for contributors to understand how to update the docs to match their contributions, and for reviewers to properly assess PRs.
This discussion is intended as a place where the KubeStellar community can map out how the site and docs and their management processes can be improved to make the site more useful and maintainable.
It is expected that points made in this discussion will be used to create issues on the kubestellar/docs repository and subsequent PRs to address the issues.
Beta Was this translation helpful? Give feedback.
All reactions