service/documentation.md

@@ -265,22 +265,31 @@ the Admin area. In Admin -> Settings -> Network -> Outbound requests:
  * add `gitlab.torproject.org` to `Local IP addresses and domain names
    that hooks and integrations can access`
 
-## Writing a TPA-RFC
+<a name="writing-a-tpa-rfc" />
+## Writing a ADR
 
-This section documents the [TPA-RFC process](policy) for people that
-actually want to use it in a practical way. The excruciating details
-of how exactly the process works are defined in [TPA-RFC-1](policy/tpa-rfc-1-policy), this
-is a more "hands-on" approach.
+This section documents the [ADR process](policy) for people that
+actually want to use it in a practical way. The details of how exactly
+the process works are defined in [ADR-100](policy/0100-adr),
+this is a more "hands-on" approach.
 
-### Should I make an RFC?
+### Should I make an ADR?
 
-Yes. When in doubt, just make a proposal. It can be as simple as
-taking a number here, writing a line in [policy.md](policy) and making an
-issue for discussion.
+Yes. When in doubt, just make a record. The shortest path is:
 
-You can even make a proposal and immediately mark it as standard (or
-even obsolete!) to just document a thought process, reasoning behind
-an emergency change, or something you just need to do now.
+ 1. pick a number in the list
+ 2. create a page in [policy.md](policy)
+ 
+    Note: this can be done with `adr new "TITLE"` with the
+    [adr-tools](https://github.com/npryce/adr-tools) and `export ADR_TEMPLATE=policy/template.md`
+
+ 3. create a discussion issue in GitLab
+ 4. notify stakeholders
+ 5. adopt the proposal
+
+You can even make a proposal and immediately mark it as accepted to
+just document a thought process, reasoning behind an emergency change,
+or something you just need to do now.
 
 ### Really? It seems too complicated
 
@@ -302,62 +311,75 @@ solve, or something that needs funding or some sort of
 justification. So the way to approach that problem will vary, but an
 exhaustive procedure might look something like this:
 
- 1. **make a plan**; brainstorm on the task list: what do you actually
-    want to do?  That's the "proposal" section in the template
-
- 2. **personas**; think about your users. make personas representing each class of
-    users, picking fun names, make sure you don't make them all dudes
-    named Steve, now is a good time to explain gender varieties, and
-    don't forget bots! you might want to look at past proposals for
-    existing personas, especially if you're reviewing a project that
-    was already targeted by a proposal
-
- 3. **review the plan**; personas will change your proposal! if you're
-    honest with yourself, you'll notice some inconsistencies and
-    negative impacts to your users. try to change your plan to
-    accommodate for that or, failing that, document why you can't in
-    the "alternatives" section
-
- 4. **requirements**; personas will inform your requirements!
-    sometimes you might *start* with requirements, but it's often
-    easier to start from users and what they need instead, and then
-    deduce requirements from there.
-
- 5. **costs**: by now you should have a good idea of what you're
-    doing. break down the tasks in digestible chunks, both in the plan
-    but also in a "Costs" section, following the [Kaplan-Moss
-    estimation technique][] (see below)
-
- 6. **timeline**: now you have a real task list, try to slot this into
-    weeks and months, starting from a fictional approval date (see the
-    proposal deadline, which you can set later or change), keep in
-    mind vacations and other projects. hint: a 1 week task will take
-    more than one week to actually execute!
-
- 7. **summarize and edit**: at this point, you have a pretty complete
+ 1. **describe the problem**; brainstorm on the problem space: what do
+    you actually want to fix?  that's the "Context and Problem
+    Statement" section of the template
+
+ 2. **describe drivers**; those are the constraints on the solutions,
+    the concerns you have to fix, external forces you have to
+    consider, those are called "requirements" elsewhere. this is where
+    you might consider Personas or affected users more explicitly, but
+    don't detail those in the proposal. instead, define those in the
+    service documentation or out of the proposal, to keep the proposal
+    short.
+
+ 3. **propose an outcome**: at this point, you might not even have
+    *made* the decision, this could merely be the proposal. still,
+    make up your mind here and try one out. the decision-maker will
+    either confirm it or overrule, but at least try to propose one.
+    
+    there are various subsections here:
+    
+    - **consequences**: this is optional. use this to document
+      possible positive/negative impacts of the proposals that people
+      should be aware of
+
+    - **confirmation**: this would be an "acceptance test" in software
+      development. how will you make sure this is correctly
+      implemented?
+
+ 4. **evaluate pros and cons**: this section is entirely optional, and
+    should be detailed only for complex problems where many solutions
+    were evaluated.
+
+ 5. **more information**: this section holds essentially anything else
+    that doesn't fit in the rest of the proposal. if this is a project
+    longer than a couple of days work, try to evaluate costs. for
+    that, break down the tasks in digestible chunks following the
+    [Kaplan-Moss estimation technique][] (see below), this may also
+    include a timeline for complex proposals, which can be reused in
+    communicating with "informed" parties
+
+ 6. **summarize and edit**: at this point, you have a pretty complete
     document. think about who will read this, and take time to review
     your work before sending. think about how this will look in an
     email, possible format things so that links are not inline and
-    make sure you have a good TL;DR: summary on top. maybe add a
-    "Background" section so people know what this is about and a
-    "Affected users" to see if they need to read it at all.
+    make sure you have a good title that summarizes everything in a
+    single line
 
- 8. **send document for approval**: this will vary wildly depending on
+ 7. **send document for approval**: this will vary wildly depending on
     the affected users, but now you should send your document and hope
     for the best. make it clear it's a proposal and that you welcome
-    changes, ideas, or dissent. give plenty of time for discussion and
-    grant extensions, if requested and possible. make it clear who
-    makes the call ("Approval" section) however. don't forget to mark
-    the proposal as such ("Proposed" status) and mark a date in your
-    calendar for when you should mark it as adopted or rejected
-
- 9. **reject or adopt**! this is it! either people liked it or not,
+    changes, ideas, or dissent. give plenty of time for discussion
+    (typically not more than two weeks) and grant extensions, if
+    requested and possible. make it clear who makes the call
+    ("decision-makers" field) and who can be involved ("consulted"
+    field) however. don't forget to mark the proposal as such
+    ("Proposed" status) and mark a date in your calendar for when you
+    should mark it as accepted or rejected.
+
+ 8. **reject or accept**! this is it! either people liked it or not,
     but now you need to either mark the proposal as rejected (and
     likely start thinking about another plan to fix your problem) or
     as "standard" and start doing the actual work, which might require
     creating GitLab issues or, for more complex projects, one or
     multiple milestones and a billion projects.
 
+ 9. **communicate**! the new ADR process is *not* designed to be sent
+    as is to affected parties. Make a *separate* announcement,
+    typically following the [Five Ws](https://en.wikipedia.org/wiki/Five_Ws) method (Who? What? When?
+    Where? Why?) to inform affected parties
+
 [Kaplan-Moss estimation technique]: https://jacobian.org/2021/may/25/my-estimation-technique/
 
 ### Estimation technique