63 lines
1.7 KiB
Markdown
63 lines
1.7 KiB
Markdown
# Document Format
|
|
|
|
## Template
|
|
|
|
```md
|
|
## Problem Statement
|
|
|
|
The problem that the user is facing, from the user's perspective.
|
|
|
|
## Solution
|
|
|
|
The solution to the problem, from the user's perspective.
|
|
|
|
## User Stories
|
|
|
|
An extensive, numbered list of user stories, covering all aspects of the feature. Each user story should be in the format of:
|
|
|
|
1. As an <actor>, I want a <feature>, so that <benefit>
|
|
|
|
<user-story-example>
|
|
1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
|
|
</user-story-example>
|
|
|
|
## Implementation Decisions
|
|
|
|
A list of implementation decisions that were made. This can include:
|
|
|
|
- The modules that will be built/modified
|
|
- The interfaces of those modules that will be modified
|
|
- Technical clarifications from the developer
|
|
- Architectural decisions
|
|
- Schema changes
|
|
- API contracts
|
|
- Specific interactions
|
|
|
|
## Testing Decisions
|
|
|
|
A list of testing decisions that were made. Include:
|
|
|
|
- A description of what makes a good test (only test external behavior, not implementation details)
|
|
- Which modules will be tested
|
|
- Prior art for the tests, that is, similar tests in the codebase
|
|
|
|
## Out of Scope
|
|
|
|
A description of the things that are out of scope for this spec.
|
|
|
|
## Further Notes
|
|
|
|
Any further notes about the feature.
|
|
```
|
|
|
|
## Rules
|
|
|
|
- **Do not include specific file paths or code snippets.**
|
|
They can become outdated quickly.
|
|
Exception: include a prototype snippet when it records a decision more precisely than prose.
|
|
Examples include a state machine, reducer, schema, or type shape.
|
|
Inline the snippet in the relevant implementation decision.
|
|
Note briefly that the snippet came from a prototype.
|
|
Trim the snippet to the decision-rich parts.
|
|
Do not include a working demo.
|