service/documentation.md

@@ -261,6 +261,122 @@ 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
+
+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.
+
+### Should I make an RFC?
+
+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.
+
+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.
+
+### Really? It seems too complicated
+
+It doesn't have to be. Take for exmaple, [TPA-RFC-64: Puppet TLS
+certificates](policy/tpa-rfc-64-puppet-tls-certificates). That was originally a short text file weasel pasted
+on IRC. Anarcat took it, transformed it to markdown, added bits from
+the template, and voila, we have at least some documentation on the
+change.
+
+The key idea is to have a central place where decisions and designs
+are kept for future reference. You don't *have* to follow the entire
+template, write requirements, personas, or make an issue! All you need
+is claim a number in the wiki page.
+
+### So what steps are typically involved?
+
+In general, you write a proposal when you have a sticky problem to
+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][], as a reminder, we first estimate each
+    task's complexity:
+
+| Complexity  | Time              |
+|-------------|-------------------|
+| small       | 1 day             |
+| medium      | 3 days            |
+| large       | 1 week (5 days)   |
+| extra-large | 2 weeks (10 days) |
+    
+... and then multiply that by the uncertainty:
+    
+| Uncertainty Level | Multiplier |
+| ----------------- | ---------- |
+| low               | 1.1        |
+| moderate          | 1.5        |
+| high              | 2.0        |
+| extreme           | 5.0        |
+ 
+This is hard! If you feel you want to write "extra-large" and
+"extreme" everywhere, that's because you haven't broken down your
+tasks well enough, break them down again.
+
+ 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
+    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.
+
+ 8. **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,
+    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.
+
+[Kaplan-Moss estimation technique]: https://jacobian.org/2021/may/25/my-estimation-technique/
+
 ## Pager playbook
 
 ### Wiki unavailable