# Write and organize documentation

Write each page for one reader goal. StormTrust uses [Diátaxis](https://diataxis.fr/) within its existing subject areas; a section does not need four empty folders to represent four documentation types.

## Choose the page type

| Reader goal            | Page form    | Frontmatter             | Completion evidence                                    |
| ---------------------- | ------------ | ----------------------- | ------------------------------------------------------ |
| Learn by doing         | Tutorial     | tutorial and difficulty | A working result or clearly labeled completed exercise |
| Complete a task        | How-to guide | how-to                  | Prerequisites, steps, and a way to check the outcome   |
| Look up exact facts    | Reference    | reference               | Fields, commands, contracts, scope, and source         |
| Understand the reasons | Explanation  | concept                 | Model, rationale, constraints, and links to tasks      |
| Choose where to go     | Section hub  | overview or navigation  | Clear paths into the relevant forms                    |

1. Read root and app `AGENTS.md`, then the StormTrust documentation skill and the vendored authoring references it selects. Search the existing section before creating another page for the same topic.
2. State the reader goal and verify the source. Use implementation for runnable commands, versioned contracts for reference, and identified requirements for planned behavior. Label a fictional exercise, proposal, or unavailable feature where a direct-link reader will see that context.
3. Choose the form from the table. Keep setup and troubleshooting in a task guide; link to it from an app reference. Keep strategic reasoning in an explanation. Do not present a target command as a working quickstart.
4. Write under `org/apps/developers/src/content/docs/stormtrust/`. Set the content type, description, products, and sidebar order. Reuse Nimbus components and the shared product/commercial status partials where their scope applies. Preserve upstream licenses and canonical URLs.
5. Link the page from its section hub and the relevant task or reference. Use the current canonical URL and heading. When moving or removing a page, update inbound links in documentation, navigation, application UI, and generated-record sources. Remove obsolete pages, duplicated explanations, and compatibility redirects; do not retain routes or anchors solely for legacy links. Preserve mirrored Cloudflare URLs and licenses.
6. Preview with `make app-dev APP=developers`. Open the page, follow its task links, inspect the sidebar, and check a narrow viewport. Run the app-owned formatter on changed content, then run:  
```sh  
make fmt  
make verify  
make app-verify APP=developers  
```
7. Search the repository for the retired paths and check the rendered link targets, including fragments. Rebuild generated discovery and Markdown artifacts from current source; do not edit or commit `dist/`. Confirm that section hubs and application links lead directly to canonical pages.
8. Follow the [pull request workflow](/stormtrust/engineering/github/pull-request-workflow/). Report any incomplete validation explicitly. The full build generates the published Markdown twins and agent corpus; a local preview alone does not prove those artifacts.

## Maintain the boundary

Update operational guides with their implementation changes. Keep exact app facts in [application references](/stormtrust/apps/), planned behavior under [Product](/stormtrust/product/), and commercial hypotheses under [Acquisition](/stormtrust/acquisition/). Link to a canonical procedure rather than copying it into each area.