January 9 2026 Docs Kickoff Call

Today 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:

1. How do we manage multiple versions of documentation for the multiple KubeStellar component repos?
   a. Which versions/releases are old enough that we can elide/ignore them
   b. Which versions are highest priority to add to the site ASAP?
2. Reexamining our semantic structure (map) to better organize the docs (with versions) of the different components
3. Documenting key Nextra techniques for our site designers:
   a) how menu structure is generated by Nextra?
   i) How much is automated via file tree now? vs How much is custom routes?
   ii) Could we start using _meta.js files instead of our custom pagemap now that we have consolidated?
   b) Can we automate site generation for a branch (version) from a file tree of MDX files?
   c) How do we accomplish the tricks with version names in bash code that were done with variables in the mkdocs version
   d) Document where key files are for contributors (message files for language support, etc)
   e) Document any key "don't touch" files for new contributors
4. Document basic doc writing process to help coders make updates.
5. What does someone reviewing PRs need to know what to do, starting right now, about PRs that affect documentation?

As a starting focus, the meeting attendees agreed on the following areas to begin work on:

Multiversion: add key kubestellar docs

1.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 process

3.a Understanding and documenting how the website navigation is generated by Nextra to ease future development

Additional items

3.b Examining/experimenting with file trees of MDX files... @KPRoche will do some experimentation when he returns later in January
4 and 5 as soon as we start decoding the menuing logic of the Nextra build engine, we can start working on the "how to write/review KubeStellar docs with an eye to the Nextra site" instructions.

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 links

The active Nextra based site is at https://kubestellar.io
The legacy mkdocs-driven site is at https://kubestellar.github.io/kubestellar
The KubeStellar github organization (with all its repos) is at https://github.com/kubestellar

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.)

• Landing Page
  • [assorted community/market pages]
  • Docs
    • [Architecture pages]
    • [Roadmap, etc pages]
    • User Guide
      • "Global" Intro Section might include the Getting Started using latest stable version)
      • KubeStellar
        • [release picker]
        • [latest]
        • [unreleased-development]
        • [previous release]
        • [previous release]
        • ⋮
      • KubeStellar UI
        • [release picker]
        • [latest]
        • [unreleased-development]
        • [previous release]
        • [previous release]
        • ⋮
      • KubeFlex
        • [release picker]
        • [latest]
        • [unreleased-development]
        • [previous release]
        • [previous release]
        • ⋮
        • [etc. etc.]
  • Contributing
    • General guidelines
    • Docs specific guidelines
    • ⋮
  • (The other high level topics)

This is a very crude map, but as I am traveling soon I wanted to record it here before I go offline.

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.

• Every page should be reachable from the navigation tree.
• Every page should be reachable by following links from one page to another, starting from the root page.
• Every non-leaf vertex V in the navigation tree should have an overview page that gives an overview of V, including links to each direct child of V (other than itself).

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).

#786
Could you please suggest what change you’d like for this issue and where it should be applied? I’ll update the docs accordingly.

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 docs/install & configure and then there is also docs/use & integrate --- and the only real "integrate" content is about ArgoCD. To me, "integrate" seems like part of "install & configure". Note also that now the KubeStellar core Helm chart has an option for installing ArgoCD and doing some integration.

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.

• The Kubernetes cluster used to host KubeFlex might be a special cluster used only for this purpose, or might be a cluster that has other purposes too and existed long before KubeFlex gets installed there. In production use it will not be a kind or k3d cluster, rather it will be a cluster that the enterprise creates in its own way.
• There may be a fixed collection of ITSes and WDSes created by the enterprise at KubeStellar setup time, or the collection might vary over time. Individual WDSes might be owned/used by different sub-units of the enterprise.
• Possibly different WDSes will distribute software to the same WECs. Imagine, for example an enterprise with a layer cake of software to distribute. Each WDS is for a distinct box in the layer cake.
• There might be one ITS and several WDSes that use it, or ITS and WDS might come and go in pairs.
• There might be a fixed collection of WECs that get created at setup time, or WECs might come and go over time.

IMPORTANT: Modification coming to kubestellar/kubestellar repository doc files

After 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.