> For the complete documentation index, see [llms.txt](https://docs.raidrobotics.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.raidrobotics.org/operations/technology/writing-raid-docs.md).

# Writing RAID docs

How RAID Docs is organized, where each kind of page is written, and the rules every page follows. Read this before you add a page or a new app's guide.

## Where things go

The header has six tabs. Put a page in the tab of the people who'll read it.

| Tab      | What goes there                                              |
| -------- | ------------------------------------------------------------ |
| Home     | The start page only                                          |
| Team     | Team Handbook, Operations, Brand, Website: how the team runs |
| Build    | Design and Manufacturing: CAD, materials, CAM and machines   |
| Controls | Programming, Electrical & Wiring, Robot Templates            |
| Apps     | One guide per RAID app                                       |
| Seasons  | Technical Design, one version per year                       |

A new robot template goes in Controls as its own section. Next season's technical design is a new version of the Technical Design section, not a new tab.

## Where each page is written

| Kind of page                                                                        | Written in                                                               | How it gets to the site                                                                                               |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| Team, Build, Controls and Seasons pages                                             | GitBook, or the [RAID\_Docs repo](https://github.com/Team4469/RAID_Docs) | Directly. GitBook and the repo stay in sync                                                                           |
| An app's guide (RAIDParts, RAIDScout, RAIDSystems, RAIDLogs) and the Robot Template | The app's own repo, in `docs/`                                           | A GitHub Action copies `docs/` into RAID\_Docs on every push to `main`                                                |
| Design and manufacturing workflows                                                  | The RaidParts repo, in `docs/`                                           | Copied into RAIDParts and, for pages listed in its `.github/docs-mirror-pages.txt`, into Design and Manufacturing too |

Never edit a copied page in GitBook: the next copy overwrites it. Copied pages say so at the top. To change one, open a pull request on the app's repo.

## Every page

* **Start with the point.** The first sentence says what the page covers or what to do. No "This page will…".
* **No empty pages.** A page needs real content before it goes in the table of contents. Leave a missing page out rather than adding a placeholder.
* **Use the words on screen.** Write button and tab names exactly as the app shows them, in bold: **Log a match**, **Manage › Users**.
* **Short and plain.** Short sentences, plain words, numbered steps for anything done in order, tables for anything compared.
* **One home per topic.** Link to the page that already covers something instead of repeating it.
* **Credit what isn't ours.** Slides, drawings and guides from other teams name the team.

## An app's guide

Every app guide uses the same layout, so a reader who knows one knows them all:

```markdown
# <App name>

<One paragraph: what the app is for and the question it answers.>

## Who this is for

| Role | What you do | Start here |
| --- | --- | --- |

## Getting started
* Sign in and get a role
* Find your way around

## <Role> guide        (one section per role, a page per task)

## Reference          (terminology, glossary, FAQ)
```

## Add a new app's guide

1. In the app's repo, write `docs/README.md` and `docs/SUMMARY.md` in the layout above, and add a `.gitbook.yaml` at the repo root with `root: ./docs/`.
2. Copy `.github/workflows/mirror-docs.yml` from RAIDLogs and set `TARGET_DIR` to the app's folder name, for example `raidlogs`.
3. Add a `RAID_DOCS_TOKEN` secret to the repo (**Settings › Secrets and variables › Actions**): a token that can write to Team4469/RAID\_Docs. It can be the same token the other apps use.
4. In RAID\_Docs, add a section for the app to the **Apps** group in `gitbook-docs.yaml`, with its folder as the space's directory.

## Moving or renaming a page

GitBook redirects a page's old address when it's moved inside its space. When a page is removed or moved somewhere new, add a redirect to the space's `.gitbook.yaml` so old links keep working:

```yaml
redirects:
  old/page-path: new/page.md
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.raidrobotics.org/operations/technology/writing-raid-docs.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
