NVIDIA / NVIDIA/simready-foundation
[docs/UX] Inconsistent feature naming and confusing, mis-sorted left-navigation
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 88
- Forks
- 18
- PR merge metrics
- No merged PRs in 30d
Description
Summary
Feature identity is inconsistent across the docs, and the left-nav is hard to read and sorted in a confusing, non-obvious order. A reader can't tell whether a feature is a "FET", an "ID:", or a name, and the same feature is labeled differently in different places.
Problem 1 — one feature has four different names
For the rigid-body feature alone, a reader sees all of these:
| Where | What it says |
|---|---|
| Left-nav (toctree) | ID:003 - RBD Physics - Base |
| Status dashboard "Name" column | Rigid Body Physics |
| Status dashboard "ID" column | FET003_BASE_NEUTRAL |
| Page H1 title | Feature: ID:003 - RBD Physics - Base |
| Page body "Internal ID" | FET003_BASE_NEUTRAL |
| Source filename | FET_003-rigid_body_physics.md |
So the same feature is "RBD Physics", "Rigid Body Physics", "FET003_BASE_NEUTRAL", and "ID:003" depending on where you look — and "RBD Physics" ≠ "Rigid Body Physics" is itself an inconsistency. It's unclear which identifier is canonical or what a reader should cite.
Problem 2 — the left-nav is hard to read
The Features sidebar labels every entry as ID:NNN - <name> - Base:
ID:000 - Core - Base
ID:001 - Minimal - Base
ID:002 - Posable Bodies - Base
ID:003 - RBD Physics - Base
ID:004 - Simulate Multi-Body Physics - Base
ID:005 - Simulate Grasp Physics - Base
...
Issues:
- It leads with a machine ID (
ID:003) that means nothing to a reader, pushing the human-readable name to the right where long names wrap onto 2–3 lines. - The
- Basesuffix is noise repeated on nearly every entry.
Problem 3 — the sort order is confusing and non-numeric
The nav is a hand-ordered toctree (nv_core/sr_specs/docs/features/features.md:46-63), not sorted. It places ID:100 between ID:011 and ID:021:
ID:007 - Non-Visual Materials - Base
ID:011 - Semantic Labels - Base
ID:100 - IsaacSim Composition ← 100 appears here
ID:021 - Core Robot
ID:022 - Driven Joints
So the order is neither numeric nor grouped by topic — it looks broken. (The number ranges appear to encode categories — 0xx core/props, 1xx Isaac, 02x robot, 03x packaging — but that grouping is invisible to the reader because the entries are interleaved and ID-led.)
Why it matters
This is the first thing a developer interacts with when trying to find a specification. Inconsistent names make it impossible to know what to search for or cite; the ID-led, wrapping, mis-sorted nav makes scanning the list of features genuinely hard.
Suggested resolution
- One canonical, human-readable name per feature, used identically in nav, page title, and dashboard (e.g. "Rigid Body Physics" everywhere). Keep the
FETxxxid as secondary metadata in a table, not as the primary label. - Nav labels = the human name, no
ID:prefix and no- Basesuffix. Show the id, if at all, as a trailing dim badge. - Group and order the nav by domain (Core, Physics, Robot, Packaging) with predictable ordering within each group, instead of an interleaved hand-ordered list.
Evidence from features.md:7-35 (dashboard) and features.md:46-63 (toctree), plus the live left-nav. Verified on main @ 2026.04.1, 2026-05-28.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with nv_core/sr_specs/docs/features/features.md, especially the dashboard at lines 7-35 and the hand-ordered toctree at lines 46-63. Compare the feature names, IDs, page titles, and source filenames, then define the canonical human-readable labels and predictable domain grouping. Done means the navigation and feature documentation use consistent names and no longer present the confusing interleaved order.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100