Split the documentation into learning, concept and reference layers - #5
Merged
Conversation
The site was six flat pages. Getting started was 308 lines covering install, body types, the fixed step, user data, ray casts, callbacks, events, sensors, filtering, joints, terrain and a pitfalls list, so looking up one subject meant scrolling a tutorial. Architecture mixed what a user needs to know about ownership with how the bindings are generated. Benchmarks led with which figures failed to reproduce in 0.2.0 rather than with what the wrapper costs. Gallery spent a third of its length on the rasterizer that drew it. Nine guides and five concept pages now hold that material, one subject each, reachable from a sidebar. Getting started is install, first simulation, the loop and where to go next. Architecture keeps only the contributor half: the submodule, the generator, the ABI dump and what CI checks. Benchmarks leads with the numbers and keeps the corrections at the end, where they still say what they said. Nothing was deleted for length. The prose that went is prose that was saying something twice, and the rest moved to the page that owns it. Cross-links point at the generated API pages, which the apiPage output format does not expose as xrefs, so they are file links rather than xref: URIs. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Readers described the site as painful to use. It was six flat pages: a
308-line Getting started that doubled as the reference for ray casts,
events, sensors, filtering, joints and terrain; an Architecture page that
mixed ownership rules with the binding generator; a Benchmarks page that
opened with which 0.2.0 figures failed to reproduce; a Gallery that spent
a third of its length on the software rasterizer.
Now
Guides and Concepts have their own
toc.yml, so each section gets a realsidebar instead of a navbar dropdown.
Not a deletion pass. Every technical claim was checked against the
source; what left a page moved to the page that owns it. Two claims were
dropped rather than repeated because I could not source them from the
code, and one rule of thumb about height field size was replaced with
ByteCount, which the reader can measure.Cross-links point at the generated API pages as file links: the
apiPageoutput format does not publish uids to the xref map, soxref:URIs do not resolve.Built with
dotnet docfx docs/docfx.json --warningsAsErrors: 0 warnings.Every anchor referenced across pages was verified against the generated
HTML, and the site was checked in a browser.
🤖 Generated with Claude Code