Skip to content

Changes

Page history
document how i write RFCs authored by anarcat's avatar anarcat
Hide whitespace changes
Inline Side-by-side
service/documentation.md
View page @ 59478bdf
......@@ -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
......