# Docs

> Write and organise your team's pages in By Dawn, review the edits agents propose, and start pages from templates.

Docs is By Dawn's wiki: runbooks, decisions and specs that live beside your tickets, where people and agents can both
read them. This page shows you how to find your way around it, write and edit pages, review the edits agents
propose, and start a page from a template.

Docs is part of some plans. If yours doesn't include it, Docs shows **Docs is not on your plan** instead. If your
organization had pages before its plan changed, they stay readable and exportable, but nobody can edit them.

## Spaces and pages

Open **Docs** from the sidebar, or press `⌘8`. Pages live in **spaces**:

- **Organization**: one space for the whole organization. Every member can read and edit it, unless an admin
  makes it private.
- **This project**: one space per project, for that project's pages. Project viewers can read it, and project
  members can edit it.

The switch at the top of Docs moves between **This project** and **Organization**. A space appears the first time
someone creates a page in it, so there's nothing to set up.

The **Pages** list on the left is the space's tree. A page with pages under it is a section: it shows how many it
holds, and opening it lists them under **In this section**. To move a page, drag it in the list: drop it between
two pages to reorder it, or onto a page to put it under that one. You can also select it and press
`⌥↑` or `⌥↓` (`Alt+↑` or `Alt+↓` on Windows and Linux).

The tabs at the top are **Pages**, **Memory** and **Review**:

- **Memory** holds short rules, concepts and decisions. Agents get the ones that matter as one-liners in every
  run, so a note is where you tell agents something once. A page holds the long-form reasoning a note points to.
  Memory is read in a project, so pick one first.
- **Review** holds the edits agents have proposed (see [Review agent edits](#review-agent-edits)).

## Create a page

1. Choose **New page**. To create it under an existing page, hover that page in the list and choose **+** instead.

2. Give it a **Title**, then pick a template (see [Templates](#templates)). **Blank page** starts empty.

3. Choose **Create page**.

In an empty space, **Create the first page** does the same.

## Edit a page

Choose **Edit** on the page. The editor is rich text: format with the toolbar or the usual shortcuts
(`⌘B` bold, `⌘I` italic, `⌘E` inline code). Type **/** for a block menu
(headings, lists, task lists, quotes, Note, Tip, Warning and Danger callouts, code blocks, Mermaid diagrams,
tables, dividers and images). Type **@** to mention a person, ticket, epic or page. A ticket ID such as `SAW-123`
typed in the text becomes a link on its own.

Paste or drop an image to add it. PNG, JPEG, GIF, WebP and SVG images are accepted. Links must start with
`https://`, or be an anchor on the same page such as `#rollout`.

The bar under the editor tells you what's saved. Press `⌘S` to save and keep editing, or choose
**Save** to save and go back to reading. **Cancel** drops your changes, and if you leave with unsaved changes, By Dawn asks
first.

If someone else saved the page while you were editing, By Dawn merges their changes into yours when it can. When the
same lines changed, it asks you to choose **Keep my version** or **Take theirs and drop my edit**.

### History, comments and links

- **History** lists every revision. Compare any one with the previous or the current revision, inline or side by
  side, and choose **Restore this revision** to bring it back. Restoring saves it as a new revision, so nothing
  in the history is lost. An agent's revisions carry a **Worker** badge that links to its ticket.
- **Comments**: select some text and choose **Comment**. Replies, **@** mentions and **Resolve** work as you'd
  expect.
- **Copy link** copies the page's link. Its menu can also copy the title as a link, or a `[[page]]` link to paste
  into another page.
- **Backlinks**, on the right, list the pages and tickets that link here. On a ticket, the **Docs** section's
  **Link a page** links a page to it by hand.
- The export button saves the page as Markdown, HTML or a PDF, and the space's header has **Export space**, which
  downloads every page as a zip file.

### Verify a page

Anyone who can edit a page can mark it as checked and still right. Choose **Verify** (or **Re-verify**), then how
long it stays verified: 1 week, 1 month, 3 months or 6 months. The page shows **Verified until** that date. When the
time runs out, it shows **Stale**, and By Dawn reminds the page's owner under **Docs to verify** in the notification bell.
Verifying a page that has no owner makes you its owner.

## Review agent edits

Agents working on tickets can propose edits to pages, for example to record a decision they made. By default
those edits wait for a person: **Nothing shows on a page until someone approves it.**

You'll see them waiting:

- on the **Review** tab in Docs, and as a dot on **Docs** in the sidebar
- under **Doc proposals** in the notification bell, and in your [Inbox](https://docs.bydawn.com/inbox/)
- in the **Doc proposals** section of the ticket that proposed them

Each proposal is one set of changes from one agent run, across one or more pages. When there's nothing to review,
the tab says **Nothing waiting for review**.

1. Open **Review** and choose a proposal. **Yours to review** lists the ones you can approve. **Waiting on
   others** lists the ones that touch a space you can't edit.

2. Choose **Show changes** to see what each page would gain and lose. A badge says how each change fits the page:
   **Applies cleanly**, **Merges with later edits** or **Conflict**.

3. Choose **Approve and apply** to save every change, credited to the agent's run and ticket. Choose **Reject** to
   drop them all.

*[Screenshot: A proposed edit on the Review tab: Waiting for review, from a Worker, with one change to the Ticket tabs page marked Applies cleanly, its diff, and Approve and apply and Reject buttons]*

A proposal is approved or rejected as a whole, not page by page. If a change has a **Conflict**, choose
**Resolve**, edit the conflicting lines, choose **Save resolution**, then approve.

Rejecting doesn't tell the agent, so if you want it to try again, say so on its ticket.

### Let agents edit directly

An org owner or admin can let agents' edits apply straight away, under
**Settings › Organization › Docs**, in **Agent doc writes**:

- **Propose**: "A person approves each agent edit before it shows on a page. The default."
- **Direct**: "Agent edits apply at once, attributed to the run and its ticket."

A space can choose differently in **Members & access › Agent edits**. Either way, every agent edit is in the
page's **History**.

## Templates

A template starts a new page with a type and a body to fill in. By Dawn has five:

| Template | For |
| --- | --- |
| **Blank page** | anything |
| **Decision record** | a decision and why it was made. It asks for a key, such as D32, that you can link with `[[D32]]` |
| **Runbook** | the steps to run or fix something |
| **RFC / spec** | a proposal for others to comment on |
| **Post-mortem** | what went wrong and what you'll change |

Your organization can add its own. They're listed under **Your organization's templates** when you create a page.
To make one:

- **From a page:** on the page, choose **⋯ › Save as template**. Give it a **Name** and **Description**, and choose
  whether it should ask for a key.
- **From Settings:** in **Settings › Organization › Docs**, under **Doc templates**, choose **New
  template**.

The person who made a template, or an org admin, can edit or delete it. A page made from a template doesn't change
when the template does.

## Who can do what

Each space gives its members one of three roles. An admin of the space sets them in **Members & access**:

| Role | Can |
| --- | --- |
| **Viewer** | read pages, history and backlinks |
| **Editor** | also write, move and restore pages, comment, and verify |
| **Admin** | also manage who has access |

A space either inherits its access (from the organization, or from its project) or is **Private**. A private space
is open only to the people, teams and projects it lists, plus org owners and admins, and it shows a lock. To review
a proposal, you need edit access to every space it touches.

## FAQ

**How do I search Docs?**

Press ⌘K (Ctrl K on Windows and Linux). The [command palette](https://docs.bydawn.com/command-palette/) searches tickets, pages and Memory
notes together, and finds a page by its title, key or a phrase in it.

**How do I delete a page?**

Not from the app yet. Move it under a page of its own, such as one called "Archive", so it's out of the way.

**Can I edit pages on my phone?**

No. On a phone, Docs is read-only. Create and edit pages in the desktop or web app.

**Can two people edit the same page at once?**

Yes. Whoever saves second gets the other's changes merged into theirs, or is asked to choose when the same lines
changed. See [Edit a page](#edit-a-page).

## Next

- [Inbox](https://docs.bydawn.com/inbox/): where proposals and stale pages wait for you.
- [Concepts](https://docs.bydawn.com/concepts/): how Docs fits with projects, tickets and agents.

Source: https://docs.bydawn.com/docs-wiki/