Documentation

[HendrikN91]

Documentation Review: Improvement Suggestions

Collection of things noticed while reading through the docs — mostly structure, navigation, and readability. Not urgent, but would meaningfully improve the onboarding experience.

Home Page

• Make the landing page more visually appealing — consider a simple diagram of a small combustor showing the flow from "3D" physics down to low-order modeling

• Limit text blocks to 4–5 lines max. Example that's currently too dense:

  "This tree is the authoritative documentation: the physics and mathematics, the numerical and architectural philosophy, and the verification and validation evidence that backs every claim."

  Convert into an enumerated list with direct links to each respective subsection

• Point new users to "Building a Network" as the recommended starting point

• Reconsider the "tracks" naming for chapters — evaluate alternative terminology

• Add direct links to each section for all chapters

Best Practices

• Reduce the number of code references crammed into a single block — break into an itemized list instead (see attached screenshot for example location)
• Reword this sentence, it reads awkwardly: "You almost never construct a CompiledProblem, call solver.solve, or index raw state vectors yourself."
• Reconsider whether "Element catalog" belongs under Best Practices — this section feels essential enough to be self-sustained
  • Consider adding small drawings/diagrams for each element
  • Consider a collapsible/hidden box with the underlying math for each element
• Fix heading mismatch: the six-step workflow example is great, but its headings don't match the subsequent section headings
• Split this chapter into two: a Quick Start (essentials only) and a separate Best Practices page
• Add a linked table of contents at the top of Best Practices for faster in-page navigation

Conventions

• No changes — this section works well as-is

Theory

Overview

• Too text-heavy — add small diagrams to improve readability

Rest of Theory

• Some phrasing reads as heavily AI-generated — revise for a more natural tone
• Add more internal links throughout to ease navigation

Second Theory Part

• Feels disconnected from the first — consider merging into the first theory section as subsections
• Currently more text-heavy than the first part — trim/rebalance
• Clarify: does "design" refer specifically to code design? Not clear from context — needs explicit framing

Validation

• For the validation map, find a way to link directly to the corresponding notebook/code for each entry

Misc

• Reader mode toggle is hard to find and occasionally buggy — investigate
• Add dark mode support (should be relatively straightforward)
• Documentation still has a number of grammar issues — consider running the full doc through a language-focused pass (e.g. ChatGPT) to generate a consolidated list of language fixes