Contributing to the Documentation

These docs are a JetBrains Writerside project. Add a Markdown file under Writerside\topics\, register it in Writerside\hi.tree, and push to main — GitHub Actions builds and deploys to GitHub Pages.

Documentation that lags the engine is worse than no documentation, because people trust it. If you change a default, add a console variable or compile out a feature, the page describing it needs to change in the same pass.

Repository layout

Adding a topic

Create the Markdown file in the appropriate Writerside\topics\ subfolder. Use Title-Case-With-Hyphens.md. Add a <toc-element topic="Your-File.md"/> entry to Writerside\hi.tree in the right section. Cross-link it. Add it to the parent section page's topic table and to the See also lists of related pages. Push to main. The workflow builds and deploys automatically.

Writerside resolves topic links by filename, not by path, so Ray Tracing works regardless of which folder either file is in. Filenames must therefore be unique across the whole project.

Writing conventions

Structure

Most pages follow the same shape:

1. # Title
2. A <tldr> block giving the answer in two or three sentences
3. Body sections
4. A ## See also list

The <tldr> is not optional on substantial pages. Readers arriving from search need to know within a sentence whether they are in the right place.

Writerside elements

Inside <tldr>, <note>, <warning> and <def>, use HTML rather than Markdown — <b>, <code>, <a href="Page.md">, <p>. Markdown syntax is not processed there.

Tone

• State the answer, then the reasoning. Not the reverse.
• Say what something costs, not only what it does.
• Where a feature is unavailable by default, say so at the top of the page, not in a footnote. The RTXDI and path tracing pages are the pattern to follow.
• Tables for enumerable facts, prose for explanation. Do not put explanations in table cells.

Accuracy

Ground claims in the engine source. Console variable names, defaults and help text should be checked against their definition rather than remembered:

Engine\Source\Runtime\Renderer\Private\        renderer CVars
Engine\Source\Runtime\Engine\Classes\Engine\Scene.h    post-process settings
Engine\Source\Runtime\Core\Public\Misc\CoreDefines.h   VITE_* compile switches

Console variable help text in the engine is sometimes out of date. HBAO+ describes itself as DX11-only in its help string but has a working D3D12 implementation. When source and help text disagree, trust the source and document the discrepancy.

Building locally

Install the Writerside plugin for a JetBrains IDE, or Writerside standalone, and open the repository root. The instance ID is hi.

Writerside's own inspections catch broken topic links, unreferenced topics and missing images, which is faster than discovering them after a deploy.

The build pipeline

.github\workflows\DocsBuild.yml runs on every push to main and on manual dispatch. It builds the hi instance with the Writerside Docker builder, uploads the artifact, then deploys to GitHub Pages.

A build failure usually means a topic referenced in hi.tree does not exist, or a topic exists but is not referenced. Both are reported by name in the workflow log.

Documenting engine changes

If your engine change affects any of the following, update the documentation in the same pull request:

See also

• Contributing
• Coding Guidelines
• Commit Conventions