[Docs]: Guide files have stale interface references and incorrect code pointers

[mrhillsman]

Documentation Type

Fix incorrect information

Location

docs/guide/

Description

Three of the four guide files have content that diverges from the current codebase. The issues fall into two categories: simple string replacements and broken mental models.

String replacements

File	Line(s)	Current (wrong)	Should be
docs/guide/README.md	14	Go 1.25+	Go 1.26+
docs/guide/03-adding-a-workload.md	18	Go 1.25+	Go 1.26+
docs/guide/01-overview.md	184	DataVolumeTemplates() []kubevirtv1.DataVolumeTemplateSpec	DataVolumeTemplates() ([]kubevirtv1.DataVolumeTemplateSpec, error)
docs/guide/03-adding-a-workload.md	478	DataVolumeTemplates() []kubevirtv1.DataVolumeTemplateSpec	DataVolumeTemplates() ([]kubevirtv1.DataVolumeTemplateSpec, error)
docs/guide/01-overview.md	275	cmd/virtwork/main.go — runE() and cleanupE(), including namespaceDataVolumes	internal/orchestrator/orchestrator.go — RunOrchestrator.Run() and related methods; NamespaceDataVolumes is in internal/orchestrator/types.go
docs/guide/03-adding-a-workload.md	477	namespaceDataVolumes in cmd/virtwork/main.go	NamespaceDataVolumes in internal/orchestrator/types.go

Mental model: Roles() → RoleDistribution()

This is not just a rename. The old Roles() returned []string (a list of role names). The current RoleDistribution() returns []RoleSpec where each RoleSpec has Role string and VMCount int, giving per-role VM counts. The orchestrator iterates RoleDistribution() and creates rs.VMCount VMs per role.

Affected locations:

• 01-overview.md line 222 — Complexity table says Network overrides Roles. Should say RoleDistribution.
• 01-overview.md line 223 — Same for TPS row.
• 01-overview.md line 227 — Prose says MultiVMWorkload extends Workload with Roles() and UserdataForRole(role, namespace). Should say RoleDistribution() []RoleSpec and explain that the orchestrator iterates the returned []RoleSpec.
• 03-adding-a-workload.md lines 539-541 — Multi-VM checklist says Implements Roles() []string. Should say Implements RoleDistribution() []RoleSpec.
• 03-adding-a-workload.md line 542 — Formula VMCount() returns Config.VMCount * len(Roles()) is wrong. The actual pattern sums RoleSpec.VMCount values from RoleDistribution().

Mental model: Orchestration moved out of cmd/virtwork/main.go

main.go is now a thin shell — runE() creates a RunOrchestrator and calls ro.Run(). All orchestration logic (planning, resource creation, secret creation, VM creation, readiness polling) lives in internal/orchestrator/orchestrator.go. The namespaceDataVolumes helper is now NamespaceDataVolumes in internal/orchestrator/types.go.

Affected locations:

• 01-overview.md line 275 — "Finding Your Way Around the Code" table points readers to cmd/virtwork/main.go for the orchestration flow. Should point to internal/orchestrator/orchestrator.go and internal/orchestrator/types.go.

Mental model: AllWorkloadNames is now derived, not hand-edited

AllWorkloadNames changed from a var slice to a function AllWorkloadNames() that calls DefaultRegistry().List(). Adding a workload to the registry automatically includes it in the name list.

Affected locations:

• 03-adding-a-workload.md lines 310-316 — Step 4 "Add to AllWorkloadNames" shows editing a var slice that no longer exists. This entire substep should be removed or rewritten to explain that names are derived from the registry.
• 03-adding-a-workload.md lines 339-349 — "Update affected tests" references counts of 5→6. The registry has 9 workloads now, and the test update story is simpler since the name list is derived.

No changes needed

docs/guide/02-deploying-workloads.md — All scenarios, expected output, verification commands, and the troubleshooting table are accurate.

Suggested Content

• Replace Go version strings
• Update DataVolumeTemplates signatures to include error return
• Rewrite the "Finding Your Way" table entry to point to internal/orchestrator/
• Replace all Roles() references with RoleDistribution() and update the mental model to explain []RoleSpec with per-role counts
• Remove the "Add to AllWorkloadNames" substep from Step 4; explain that names are auto-derived from DefaultRegistry()
• Update test count references from 5/6 to 9/10
• Update namespaceDataVolumes references to NamespaceDataVolumes in internal/orchestrator/types.go