Write or update documentation

Add a page or revise an existing one so readers can learn, complete a task, look up a fact, or understand a design.

Before you begin

Work in the website repository with its Node.js/npm environment. Read AGENTS.md and check the relevant Core, Applications or Platforms source at a known revision for technical claims.

Choose the page’s purpose

Reader’s need	Type	Directory
Learn through a guided example	Tutorial	src/tutorials/
Complete an independent task	How-to	src/how-to/
Look up exact options, defaults, errors, or APIs	Reference	src/reference/
Understand a concept, relationship, or trade-off	Explanation	src/explanation/

The structure follows Diátaxis. Local writing templates are informed by The Good Docs Project.

Write the page

1. Copy the appropriate file from docs/templates into the selected source directory.
2. Replace the title, description, and all writing prompts. Keep the correct docType value and remove unused sections.
3. State who the page helps and what they will achieve. Put environment/artifact prerequisites before procedural steps.
4. Specify each command’s directory and whether it runs in the host shell, Devbox shell, browser console, or Xila terminal.
5. Add observable results to tutorials and completion checks to task guides. Keep exact lookup tables in reference pages and design reasoning in explanations.
6. Link to related page types instead of duplicating their procedures or reference tables.

Keep the published content in English and preserve technical identifiers exactly. Do not claim commands, hardware support, or runtime behavior were verified unless they actually were.

Make Explanation pages progressive

Explanation should help a reader build a mental model before asking them to understand implementation details. Prefer a cognitive order, not a mandatory heading template:

1. explain what the concept/component is and why Xila needs it;
2. give a short mental model or faithful analogy when it helps;
3. show how it relates to neighboring parts of Xila;
4. describe one concrete interaction in narrative form;
5. introduce the few Rust abstractions that embody the design;
6. move current data structures, locks, runner loops, and other internals into a deeper section such as Under the hood;
7. finish with the architectural consequences, trade-offs, boundaries, and deliberate links to related documentation.

Do not turn the concrete interaction into a setup procedure. For example, an Explanation page can describe what happens when an executable opens /data/config.json, but the reader should not be instructed to perform those steps. If the reader’s next question is how do I do this?, link to a How-to or Tutorial instead.

Likewise, avoid reproducing exhaustive error lists, option tables, command matrices, or method inventories. Keep facts that explain a boundary or trade-off, then point to Reference/Rustdoc for exact lookup detail.

Use diagrams to teach one idea

For introductory Mermaid diagrams:

• show one relationship or flow at a time;
• normally keep the diagram to roughly 4–7 primary nodes;
• prefer human labels (Task manager, Interface stack, Platform driver) over Rust implementation names;
• keep RwLock, BTreeMap, StackInner, refcounts, and similar internals out of the first diagram;
• explain in prose what the reader should notice after the diagram.

flowchart LR works well for architecture/ownership relationships, while sequenceDiagram is useful for describing a concrete request journey. A second implementation-level diagram may use exact Rust types once the page has established the conceptual model.

Link Rustdoc at the point of explanation

Use HostReference and GuestReference inline when a public Rust symbol gives precision to the concept being discussed. The surrounding sentence must still explain what the symbol means; readers should not need to click the link to understand the page.

A reference can target a crate, a top-level Rustdoc symbol, or an associated-item anchor. For example:

<HostReference crate="virtual_file_system" kind="struct" symbol="File" member="method.open">opening a file</HostReference>

member is the raw Rustdoc anchor (for example method.open, associatedconstant.NAME, or associatedtype.Item), not a website-specific taxonomy. Only use it after verifying the generated symbol/anchor. Keep CodeReference for source or example code whose implementation materially helps the explanation, rather than linking source merely because it exists.

Source repositories after the split

CodeReference defaults to Core. Set repo="applications" for Wasmi and official executable sources, or repo="platforms" for platform drivers, examples and deployment files. For an exact moved file, use its full path relative to that repository’s root.

HostReference and GuestReference also accept repo. Core host references still use the deployed Rustdoc viewer. Because external Applications/Platforms Rustdoc is not deployed at the former Core Pages URLs, those references link to the crate’s GitHub source directory rather than a symbol-specific page.

CI checks paths against current Core, Applications and Platforms checkouts. Locally, provide XILA_CORE_PATH, XILA_APPLICATIONS_PATH and XILA_PLATFORMS_PATH to enable all source checks.

Connect the page

Update its section landing page and astro.config.mjs. Link to it from relevant existing pages and the component map when appropriate.

When moving a page, update incoming links and anchors. The site is pre-production; the current workflow moves pages directly without legacy redirects.

For API/source links, use the existing HostReference, GuestReference, and CodeReference components after checking their crate, symbol, member anchor, or source path. Keep templates outside src/ so writing prompts never appear in the public site or search.

Validate the change

From the website repository root:

npm ci
npm run format:fix
npm run check

check verifies Rustdoc-reference path behavior, formatting, the production site/search build, and documentation links/anchors. Review format:fix’s diff; for a focused change, run Prettier on only the changed files instead.

Preview the production build with npm run docs:preview, check the navigation and reader journey, then run git diff --check.

For an Explanation rewrite, also compare the old and new page specifically for technical fact loss. Every removed implementation fact should either still exist deeper in the page, be deliberately replaced by an authoritative Reference/Rustdoc link, or be intentionally removed because it was stale or did not help explain the design.

Verify completion

The page should be discoverable from its section, satisfy one primary reader need, and have no unresolved writing prompts or broken internal links. Explanation pages should establish their mental model before implementation internals. Review the diff for technical facts lost during splitting, and state which checks actually ran.