Update Docs

Update Documentation

Update the hand-written guides in docs/ to reflect code changes.

Critical Rule

NEVER touch docs/api/ — that directory is auto-generated from XML doc comments by a CI workflow on each release. Do not edit, regenerate, or reference its contents as a source of truth for writing guides.

Step 1: Identify What Changed

Read the code changes (new files, modified files, git diff) to understand:

• What user-facing APIs or behaviors were added/changed/removed?
• Are there new public types, methods, properties, or parameters?
• Were any existing signatures changed (renamed, removed, new required params)?

Step 2: Find Affected Docs

The hand-written docs live in docs/. Use this mapping to find the right file:

If a change spans multiple topics, update all relevant files.

Step 3: Read the Existing Section

Read the target doc file before editing. Understand:

• Where the relevant section is (or where a new section should go)
• The style and depth of surrounding content
• Whether tables, code blocks, or prose are used for similar content

Step 4: Write the Update

Follow the existing style of the document. General conventions:

Audience

These docs are for game developers using the engine, not engine contributors. Write from the perspective of someone building a game:

• Focus on what developers can do — public API, usage patterns, configuration options
• Skip internal implementation details — don't mention internal classes, private fields, engine subsystem wiring, or how systems work under the hood unless it directly affects how the developer uses the feature
• Explain "why" only when it affects usage — e.g., "Layout uses flexbox, so children flow like CSS flex containers" is useful. "Layout syncs styles to Yoga nodes then reads back computed rects" is not.
• Don't document internal types — if a class is internal, it doesn't belong in the docs
• Keep code examples practical — show realistic game scenarios (HUD, menu, gameplay), not engine test harnesses

Style

• Code examples: Use fenced C# blocks with using statements when showing API usage for the first time in a section
• Property tables: Use | Property | Default | Description | format
• Type/field tables: Use | Field | Type | Description | format
• Section hierarchy: ## for major topics, ### for subtopics within them
• Tone: Direct, concise, second-person ("Add a component", "Cast a ray")
• Removed APIs: Delete the old documentation entirely — do not leave stubs or deprecation notes unless backward compatibility shims exist in code
• New sections: Place them in logical order relative to existing content (e.g., a new raycast filtering section goes inside the existing Raycasting section, not at the end of the file)

Step 5: Update docs/README.md If Needed

If a new guide file was created, or if an existing guide's scope changed significantly, update the tables in docs/README.md to reflect it.

Checklist

• Only hand-written docs in docs/ were edited (not docs/api/)
• Code examples compile and use current API signatures
• No references to removed/old API signatures remain
• Property/field tables match the actual code
• New sections are placed logically within existing structure
• docs/README.md index is up to date if guides were added/renamed

Converted and distributed by TomeVault — claim your Tome and manage your conversions.