RFC: Reorganize the HAMi docs. Which one should I use: HAMi, HAMi-DRA, Volcano vGPU, or KAI Scheduler?

[archlitchi]

We're reorganizing hami-project.io. Before we rebuild it, tell us what's broken.

Full plan: Google Doc

3 problems we keep hearing:

1. Hard to navigate. The docs are a flat list. New users don't know where to start.
2. HAMi or HAMi-DRA? Both are documented, but nothing says when to pick which.
3. Capabilities don't match. HAMi / HAMi-DRA / Volcano vGPU / KAI Scheduler don't do the same things. Users only find out in production.

What we'll build (react to each):

1. Guided nav: Get started → Concepts → Install → Pick your approach → Vendor guides → Integrations → Operate
2. One "HAMi vs HAMi-DRA" decision page
3. A capability matrix showing who supports what

Answer any of these (one line is fine):

1. Which doc do you open first? Which is hardest to find?
2. Why did you pick HAMi or HAMi-DRA?
3. Do you run HAMi with Volcano or KAI? What's missing from those guides?
4. If we add a "choose your path" flow, what should it ask first?

We're targeting completion by Aug 14, 2026. Comment by Aug 14. Or chat in Slack / Discord.

/area docs
/kind documentation

[archlitchi]

CC @mesutoezdil @fishman @rootsongjc

[coderabbitai]

🔗 Related PRs

#425 - docs: add 5-minute quick start path (#412) [merged]
#530 - docs: update CNCF status from Sandbox to Incubating [merged]
#602 - docs: fix HAMi pod label selectors and Helm value references [merged]
#604 - docs: fix scheduler policy flag, schedulerName case, and stale link [merged]
#612 - docs: fix kai-scheduler hamicore install flags (guide + blog + zh) [merged]
#613 - docs: add NVIDIA CDI configuration guide [merged]
#704 - docs(structure): reorganize website content and navigation [merged]
#712 - docs(get-started): simplify quick start and online installation guides [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[singhsrijan46]

@archlitchi
I would like to work on this issue. Please assign it to me.

[fishman]

@singhsrijan46 you can suggest changes or submit a PR.

@archlitchi I agree, it's "crowded" as they say

[WaliTheOrchestrator]

I am currently working on my proposal. I will try my best to present it in upcoming english meeting on wednesday

[AyushSrivastava1818]

The missing piece isn't any single doc — it's the "which one do I even use" page
that should exist before the installation guides.

Two things a comparison page should say plainly, up front:

1. HAMi vs HAMi-DRA: pick classic HAMi unless you're on K8s ≥1.34 with the
   DRA Consumable Capacity feature gate and specifically need DRA's resource
   model — the two modes are mutually exclusive, and HAMi's own KCD Beijing talk
   admits DRA's UX is currently worse. That admission is buried in a blog post;
   it should be on the docs page where people are deciding.
2. HAMi vs KAI/Volcano: these aren't really alternatives to HAMi — KAI and
   Volcano handle scheduling (who gets a GPU fraction, when), HAMi-core handles
   isolation (enforcing that fraction at runtime). KAI's own docs never mention
   that a pod requesting 20% of a GPU can still use 100% without HAMi-core
   underneath — and NVIDIA's KAI Scheduler has already adopted HAMi-core for
   exactly that reason. That pairing should be stated, not left for people to
   discover via a blog post.

One page making both of those explicit would resolve most of the "which one do
I use" confusion the flat list currently causes.