diff --git a/docs/rules/DEV-125.md b/docs/rules/DEV-125.md index 317dfcc..8ed1c58 100644 --- a/docs/rules/DEV-125.md +++ b/docs/rules/DEV-125.md @@ -4,14 +4,14 @@ title: "Write a Spec in the Standard Format" status: "active" enforcement: "manual" severity: "error" -depends_on: ["DEV-180", "DEV-350"] +depends_on: ["DEV-180", "DEV-350", "DEV-390"] --- ## Problem A Spec written without a shared structure is hard to read and review: readers -cannot tell where the goal, the overview, or the behavior sections are, and -specs drift into describing internals instead of user behavior. +cannot tell where the objective, the user types, or the behavior sections are, +and specs drift into describing internals instead of user behavior. ## Solution @@ -21,19 +21,39 @@ about what users can do, not how the system works. 1. Store the Spec as a markdown file under `docs/specs/`, linked from its Goal under `# Spec`; its sections graduate to `docs/product/` per [DEV-180](./DEV-180.md). -1. Start with `goal:` frontmatter linking the Goal, then an H1 feature name and - a `## Overview` of what the Goal enables for users. -1. List every user type in `## User Types`, including operator and administrator - types that are not the client's end-users. If a type's account is provisioned - outside the product (database seed, manual setup), say so, and say whether - the product can create more of them. -1. Treat the user account as a key concept, not as a separate administration - area: creating, listing, granting access to, and removing accounts are - actions on it like any other. -1. Name the permitted user type in every action. An action with an implicit - actor cannot be reviewed against what the product actually allows. -1. Add author-defined `##` sections that describe observable user behavior, not - internal mechanics. +1. Carry only what is new: behavior the Goal adds or changes. Where the product + docs already explain something the Spec refers to, such as a user type, an + object, a capability, or a term, do not explain it again: name it as the + product docs do and link to the section that explains it. + [DEV-390](./DEV-390.md) keeps that section matching the product. The product + docs change only when behavior ships, per [DEV-180](./DEV-180.md), not when + the Spec is written. +1. Start with `goal:` frontmatter linking the Goal, then an H1 feature name of + at most 30 characters. Name the feature as a noun phrase, not a sentence. +1. State in `## Objective`, in at most 250 characters, the business value and + the user problem it solves. +1. List exactly three `## Key Results` as a numbered list, each at most 160 + characters. Each is a measurable outcome, and together they define success. +1. List every user type the Spec's actions name in `## User Types`, including + operator and administrator types that are not the client's end-users. A type + the product docs already explain is named and linked to that section, with + nothing explained again. A new or changed type gets, in at most 150 + characters, its definition and who creates the account: another user type, + the user by signing up, or a process outside the product such as a database + seed or manual setup. For an account created outside the product, say whether + the product can create more. +1. Give each object users interact with its own `##` section, starting with + `## User Account`. Treat the user account as an object, not as a separate + administration area: creating, listing, editing, granting access to, and + removing accounts are actions on it like any other. +1. Give each capability on an object its own `###` subsection, named for what + the user does, such as "Funding an account". +1. Write each action as its own item that starts with the user types permitted + to perform it: `- [User Type], [User Type] can [action].` An action with an + implicit actor cannot be reviewed against what the product actually allows. +1. Describe observable user behavior, not internal mechanics. +1. Keep the template's guidance in HTML comments. They do not render, so a + partly written Spec shows readers only its content. 1. Include a `## Design` section using the markup in [DEV-350](./DEV-350.md) when the Goal has a design component. @@ -42,40 +62,94 @@ about what users can do, not how the system works. goal: --- -# Feature Name (max 45 chars) +# [Feature Name] + + ## Objective -(describes business objective, max 250 chars) -## Key results -(three items; max 160 chars each) + + + +## Key Results + + + + +1. [Key Result 1] +1. [Key Result 2] +1. [Key Result 3] ## User Types -(list of every user type and its short definition, operators and -administrators included; each item max 150 chars. Note any type whose -account is provisioned outside the product, and whether more can be -created in the product) -## Key Concepts + + + +- **[User Type]:** Defined in [the product docs](../product/[page].md#[user-type]). +- **[User Type]:** [Definition]. Created by [User Type, or self sign-up]. +- **[User Type]:** [Definition]. Created outside the product by [database seed, manual setup]. The product [can, cannot] create more. + +## User Account + + + +Defined in [the product docs](../product/[page].md#user-account). + +### Creating an account + +- [User Type], [User Type] can create a [User Type] account. + +### Listing accounts + +- [User Type] can list [User Type] accounts. + +### Editing an account + +- [User Type] can edit a [User Type] account's [details]. + +### Granting access + +- [User Type] can grant a [User Type] account access to [Object]. + +### Removing an account + +- [User Type] can remove a [User Type] account. + +## [Object Name] + + + +Defined in [the product docs](../product/[page].md#[object-name]). -(subsections describing key concepts users need to know about; the -relevant methods (actions) each permitted user type can use. Include the -user account itself as a concept, with its create, list, access, and -remove actions. Name the permitted user types in every action) +### [What the User Does] -## [Section] + + -Describe what users can do, not how the system works internally. +- [User Type], [User Type] can [action]. ``` ### Acceptance Criteria -- [ ] The Spec is a `docs/specs/` file with `goal:` frontmatter, an H1 name, and - a `## Overview` -- [ ] `## User Types` covers every type, operators and administrators included, - states how any externally provisioned account comes into existence, and - says whether the product can create more of that type -- [ ] The user account appears in `## Key Concepts` with its own actions -- [ ] Every action names the user types permitted to perform it +- [ ] The Spec is a `docs/specs/` file whose `goal:` frontmatter links its Goal, + with an H1 noun phrase of at most 30 characters +- [ ] The Spec carries only what the Goal adds or changes +- [ ] Nothing the product docs already explain is explained again; the Spec + names it and links to the section that explains it +- [ ] Writing the Spec adds nothing to the product docs +- [ ] `## Objective` states the business value and the user problem in at most + 250 characters +- [ ] `## Key Results` is a numbered list of exactly three measurable outcomes + of at most 160 characters each +- [ ] `## User Types` covers every type the actions name, operators and + administrators included, linking types the product docs explain and + defining new or changed ones with who creates the account, and, for an + account created outside the product, whether the product can create more +- [ ] `## User Account` is the first object section, covering creating, listing, + editing, granting access to, and removing accounts, by content or by link +- [ ] Each object has its own `##` section with a `###` subsection per + capability, named for what the user does +- [ ] Every action is its own item starting with the user types permitted to + perform it - [ ] Sections describe user-observable behavior, not internal mechanics - [ ] A Goal with a design component includes a `## Design` section per DEV-350