NVIDIA / NVIDIA/simready-foundation

[docs/UX] Inconsistent feature naming and confusing, mis-sorted left-navigation

Open
#9 0 comments 0 reactions 0 assignees View on GitHub

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 - Base suffix 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

  1. One canonical, human-readable name per feature, used identically in nav, page title, and dashboard (e.g. "Rigid Body Physics" everywhere). Keep the FETxxx id as secondary metadata in a table, not as the primary label.
  2. Nav labels = the human name, no ID: prefix and no - Base suffix. Show the id, if at all, as a trailing dim badge.
  3. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.