Documents

A document in dot•requirements is a container for related requirements. It’s a familiar format — like a Google Doc or a Markdown file — with special requirement blocks embedded inside.

Documents Are Just Documents

Write prose, add context, organize however makes sense. Documents support all the formatting you’d expect: headings, lists, links, code blocks — and a code block whose language is mermaid renders as a diagram, with a toggle back to its source. On disk it stays a plain fence, so the same diagram renders on GitHub too.

This is particularly helpful for adding research, market analysis, customer quotes, technical constraints, and other context that your team needs to make informed decisions. All that context then lives alongside your requirements and syncs to your team with everything else. Documents can serve as the full range of product documentation.

The key difference from a Google Doc or Confluence page is that a dot•requirements document can also contain requirement blocks — structured, testable statements that developers reference in their tests.


# Login Flow
 
This document covers authentication requirements for the main login page.
 
## Background
 
Users authenticate with email and password. We support password reset
via email link. Passkeys are out of scope for v1.
 
## Research
 
In customer interviews, login friction was a top complaint:
 
> "I forget my password constantly. The reset flow needs to be dead simple."
> — Customer interview, Jan 2026
 
Analytics show 23% of users abandon at the login screen. Our hypothesis
is that a clearer error message and streamlined reset flow will reduce this.
 
## Requirements
 
```dotrequirements
LOGIN-1: A registered user, Jamie, can log in to their account
  0. → When Jamie provides their registered email and correct password, they are authenticated and brought to their dashboard
  1. → When Jamie provides an incorrect password, they see an error message and remain on the login page
  2. → When Jamie fails to log in 5 times in a row, their account is temporarily locked
```
 
```dotrequirements
LOGIN-2: A registered user, Jamie, can reset their password
  0. → When Jamie requests a password reset, a reset link is sent to their registered email
  1. → When Jamie clicks a reset link older than 24 hours, they see a message that the link has expired
```

The prose (“Background”, “This document covers…”) provides context. The requirement blocks (LOGIN-1, LOGIN-2) contain the testable units that developers reference in their code.

Working with Documents

Product managers and stakeholders compose and edit documents in the web editor at app.dotrequirements.io . The editor provides rich formatting, drag-and-drop, and an AI assistant to help you write.

Developers sync documents into their codebase as .requirements.md files — plain Markdown that works in any editor and renders nicely on GitHub.


my-project/
├── .requirements/
│   ├── login-flow.requirements.md
│   └── checkout.requirements.md
├── src/
└── tests/

Documents also appear in Jira and Confluence if you’ve installed the Atlassian add-ons.

Customers, executives, and other reviewers often need to read a document without joining your team. Open a document’s Share control and turn on Anyone with a link can view. You get a link that shows the document’s published version, read-only, to anyone who opens it — no account, no sign-in, no install.

Sharing is off until you turn it on, and it’s per document: turning it on for one document doesn’t expose any other.

Turning it off stops the link working. Turning it back on restores the same link, so anything you’ve already sent keeps working — a shared link is public and identifies no particular reader, so the switch controls whether the document is readable, not who is reading it. Share it with that in mind.

Because reviewers read the document itself, it’s worth writing the surrounding context into it — a problem summary, key decisions, what’s out of scope, open questions — alongside the requirement blocks. The web assistant can add those sections for you.

This is separate from Share with developers, which hands a developer a dotreq sync --share command for pulling a whole project’s requirements into a codebase.

Syncing Documents

dotreq sync reconciles documents between the cloud and your local codebase. With no flags, both sides contribute their additions:


dotreq sync

Direction flags narrow it — --cloud-contributes only brings the cloud’s additions down, --repo-contributes only sends the repo’s up — and --repo-wins / --cloud-wins make one side authoritative. dotreq diff shows the comparison first, without changing anything.

A document is one live, shared body — everyone who edits it (the web editor, the AI assistant, a chat agent) is editing the same thing, and edits appear for everyone as they’re made. Publishing is a separate, deliberate step that takes a copy of the document as it stands; that published copy is what dotreq sync pulls into repos. Work in progress never reaches a developer’s checkout until someone publishes it.

Organizing Your Documents

Projects are at the product level — one project per codebase or product. A project might be “My App” or “Backend API”.

Documents are at the epic or feature level — one document per cohesive set of requirements. A document might be “Login Flow”, “Checkout Process”, or “User Profile”.

This keeps documents focused and manageable. If a document grows too large, the web assistant or your AI coding assistant can help you split it into multiple documents.

Next Steps

Learn about requirements — See Requirements for the structure and format of requirement blocks
Try the web editor — Create a document at app.dotrequirements.io