Docs style guide

Write for the person trying to complete the page's task. Players should not need programming knowledge to install a mod. Beginner tutorials explain the new concepts they use. Reference pages keep precise contracts easy to look up.

Voice

Use second person, present tense, and concrete actions: “Save main.lua, restart Red, then read the Pallet Town sign.” Explain unfamiliar terms at first use and link to the Glossary. Keep exact API names and capitalization; explain them instead of inventing friendlier code names.

Assume curiosity, not prior engine knowledge. Avoid phrases such as “just,” “obviously,” “trivial,” or “without hand-holding.” More words are useful when they resolve a missing step; repeating the same boilerplate is not teaching.

Match the page to the reader

Page kind	Opening	What must be easy to find
Player guide	The task and app controls	Steps, expected result, common failure/recovery
Beginner tutorial	Goal, target game, prerequisites	Exact files, complete examples, explanations, checkpoints
Concept	A practical question or choice	Plain model, small worked example, precise rules
Cookbook	One task and required context	Paste location, dependencies/assets, result, fuller walkthrough
Reference	Purpose and notation	Contract, types, scope, example status, source
Advanced guide	Audience and required experience	Main workflow first, advanced matrix/edge cases afterwards

Use the beginner template when appropriate: goal → prerequisites → where to work → one step → why it works → check → recovery → complete files → next page. Do not force that entire structure onto every reference entry.

Cite your source

Verify engine behavior in the relevant source, test, or supported app flow before stating it. Keep source references after the explanation or under technical notes. A source path is evidence, not an explanation by itself. Where useful, link to the file in the engine repository.

Document the supported user workflow. Do not infer that a low-level API's existence makes every route supported. In particular, Link Play uses the launcher and vanilla carts or sealed custom carts; active mods are permitted through the sealed-cart workflow, not as a freely chosen mod set.

Names

Copy identifiers exactly: baseStats and catchRate are camelCase fields; map_scripts is a registry name. A display name and an internal ID are not interchangeable. Explain registry, record, manifest, hook, event, and other terms locally on beginner pages; use Modding Basics for the shared foundations.

Keep existing page names and useful section anchors when reorganizing. Add a link or anchor alias if a renamed section has incoming links.

Code and snippet tags

Every code block needs reader-visible context: Complete file, Insert inside the entry function, Console input, or Outline only. State the file path, required assets/IDs, and whether another example must exist. An HTML comment is not visible to the reader.

Retain these annotations above Lua fences as authoring metadata:

• <!-- snippet: run -->: intended to run in the stated context. A fragment still needs the visible insertion instruction; the tag is not a claim that it is a complete file.
• <!-- snippet: expect -->: intended example with expected output below it.
• <!-- snippet: illustrative -->: shape, signature, console input, optional sketch, or example with omitted/external setup. Say what is missing.

The current checkout has Modkit's loader validation and reference generation; it does not have a general wiki-fence runner that proves every tagged block works. Do not claim hidden harness execution, tag coverage, or gameplay verification that has not been run. Validate complete tutorial folders, then check the promised behavior separately.

For beginner exercises, show complete valid JSON. Do not use ellipses in a required runnable file. Keep optional outline code clearly separate from the main checkpoint. For required art/audio, provide original example assets, exact file paths, and format requirements verified against their consumer.

Commands and observations

Before a command, name the working directory and required tools. Distinguish engine root, wiki root, and mod root. Explain replaceable placeholders and quote paths with spaces. Prefer one actual command over usage grammar on a beginner path; reserve [optional] notation for tool reference.

After a command, state its output location or meaningful result and the first recovery step. Distinguish syntax checks, loader validation, and observable in-game success. A “valid” mod can still reference an asset or callback that fails when used. “Watch the log” must link to Troubleshooting.

Give checkpoints a reachable location/state and an action. For random or numerical behavior, supply a controlled inspection/comparison rather than asking a learner to infer correctness from one battle.

Formatting and visuals

Use headings, fenced blocks with language tags, and short comparison tables. Wrap prose near 80 columns where practical. Escape pipe characters inside Markdown table cells, including type expressions. Use diagrams when they explain file layout, coordinates, state, or callback order more clearly than prose. Give images useful alternative text and captions; do not use color as the only way to communicate a distinction.

Avoid repeating full engine field inventories on the homepage. Put advanced explanations after a first complete workflow. Preserve useful technical detail instead of silently deleting it during a readability pass.

Change + doc

When a feature changes, update affected instructions, examples, and references in the same work. Keep claims about supported games and UI labels synchronized with the implementation rather than preserving an obsolete page by habit.

Name the games a claim covers. The engine runs eleven games across three generations (GameVersion.ORDER in src/core/GameVersion.lua); a sentence that is true only on Gen 1 says so, and a sample that needs Gen 2 or Gen 3 shows the manifest games (and "api": 3 where it relies on the portable API). Check Gen 2 and Gen 3 behavior against docs/mod-api-gen2-compat.md, docs/mod-api-gen3-compat.md and python3 tools/modkit.py gen2check / gen3check, not against Gen 1.

Do not use the em-dash character; use a colon, comma, parentheses or a hyphen.

Reference-Registries.md is generated. Change tools/gen_registry_docs.lua for presentation and src/mods/Schemas.lua for schema-owned material. Never hand-edit the generated body.

From the engine root, with LuaJIT installed, regenerate this wiki using its actual path. For this common sibling layout:

luajit tools/gen_registry_docs.lua ../pokemon-gen1-recomp-project-wiki

Replace the final argument if your wiki folder has another name. Without an explicit target the generator writes docs/modding/reference/registries.md inside the engine checkout. Keep committed generated outputs synchronized when the generator changes. modkit docs --out DIR exports registries.md; it is not the same filename as a direct wiki generation.

Repeatable structural check

From any directory, run python3 /path/to/wiki/examples/check_wiki.py, replacing the path with this wiki checkout. It checks local pages and anchors, raw example targets in this checkout, balanced fences, and complete JSON blocks. It does not fetch external links or execute Lua. Complete example validation and behavior-test commands are documented in examples/README.md.

Before sharing a documentation change

• Check the audience, prerequisites, file placement, target game, and first-use definitions.
• Compare the walkthrough against its complete example files; eliminate contradictory IDs, asset names, and state ownership.
• Run the relevant Modkit checks and behavior tests for changed examples; record what was actually tested.
• Check links, anchors, table rendering, and generated-reference consistency.
• Review the first workflow from a fresh reader's point of view. Human usability sessions are valuable; label an agent/source review honestly.

Do not publish, commit, or claim a human test merely because a documentation check passed. Follow the user's requested review and publication workflow.