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.

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 pull 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.

Syncing Documents

Pull downloads documents from the cloud to your local codebase:

dotreq pull

Push uploads local changes back to the cloud:

dotreq push

Documents have draft and published states. The CLI always works with published versions — draft edits in the web editor don’t affect what developers pull until you publish.

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 MCP 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