diff --git a/docs/rules/DEV-230.md b/docs/rules/DEV-230.md index 5bebb30..493f600 100644 --- a/docs/rules/DEV-230.md +++ b/docs/rules/DEV-230.md @@ -25,17 +25,23 @@ applied to every issue, PR description, comment, review reply and chat message. own hesitation or worry. 1. Cut openers that announce a point instead of making it, such as "Worth noting", "Just to add" or "Good question". -1. End with what you need, from whom. When nothing is needed, stop. +1. End with what you need, from whom. When nothing is needed, stop. A hedged + closer such as "Feel free to ask" or "Let me know if you have any questions" + asks for nothing, so cut it. +1. Join clauses with a comma, colon, period or parentheses, which say how the + parts relate. An em dash does not show how the parts relate. Use an en dash only in a number range. ```md Good: Blocked on the MAS field list. @owner, which company fields does MAS receive? I need it to finish the edit gate. Bad: Hi @owner, hope you're well! Great work on the spec so far. I've been looking into the edit gate and I'm a bit worried about the fields... + Let me know if you have any questions. ``` ### Acceptance Criteria - [ ] The first line carries the decision, answer, status or question -- [ ] The message holds no greeting, flattery or personal aside +- [ ] The message holds no greeting, flattery, personal aside or hedged closer - [ ] A message that needs something from someone names what and from whom +- [ ] No em dash appears in prose, and an en dash only inside a number range diff --git a/docs/rules/DEV-260.md b/docs/rules/DEV-260.md new file mode 100644 index 0000000..80c7533 --- /dev/null +++ b/docs/rules/DEV-260.md @@ -0,0 +1,41 @@ +--- +id: DEV-260 +title: "Define Every Term the Reader Has Not Seen" +status: "active" +enforcement: "manual" +severity: "warning" +depends_on: ["DEV-230"] +--- + +## Problem + +A message built on words the reader has not seen defined, such as "middle +ground" or "eng-month", makes them guess, and two readers guess differently. + +## Solution + +A word earns its place only if it survives the question "what does that mean +here?". The writer knows what they meant; the reader only has the page. + +1. Replace an abstract verb such as "align", "streamline", "formalise" or + "leverage" with the action it stands for. +1. Replace a catch-all such as "everything else" or "the rest" with the list it + covers. +1. Define a term the first time you use it, unless the thread or a linked doc + already defines it. Otherwise replace it with the concrete thing. +1. Refer to an earlier position by stating it or linking it, not by a shorthand + only you hold. + +```md +Good: A month with under 40 logged hours bills by the days worked, not as a + full month. +Bad: This keeps partner protection on light months (no "16h = full month"). +``` + +### Acceptance Criteria + +- [ ] Every unfamiliar term is defined in the message, the thread, or a linked + doc +- [ ] No abstract verb stands in for an action that can be named +- [ ] No catch-all stands in for a list that can be given +- [ ] Every earlier position referred to is stated or linked diff --git a/docs/rules/README.md b/docs/rules/README.md index 736b060..050c008 100644 --- a/docs/rules/README.md +++ b/docs/rules/README.md @@ -67,6 +67,7 @@ Where discussion goes, how a message is written, and how work is referenced. - [DEV-240](./DEV-240.md): mention someone only to ask them to act - [DEV-245](./DEV-245.md): post a daily update on the work you own - [DEV-250](./DEV-250.md): settle it async before calling a meeting +- [DEV-260](./DEV-260.md): define every term the reader has not seen ### 3. PR requirements