Documenting decisions made via forum

Clearing the Path
1

Continuing the discussion from Process for consent decisions on the forum:

Once we make a decision by consenting on a proposal, we should capture the decision appropriately. So, the initial one was on the process for consenting.

Where / how should we capture that in a reliable place that isn’t just the forum post in the history? Wiki? Governance repo in GitLab?

2

I agree that keeping the documents in the forum only is suboptimal. The governance repo you mentioned would have the following advantages:

  • It is already established as the place for governance docs: It contains docs and the wiki links to it.
  • AFAICT it contains information that is not up-to-date anymore (?); using it as the Single Source Of Truth would probably fix this, at least incrementally.
  • Since it’s a git repository, we would have more confidence that the history cannot be lost. (In comparison to the forum. The wiki has the same advantage.)

The wiki would have the following advantages:

  • It’s a git repository too
  • It is displayed in a more readable, less distracting way
  • In theory, it can be edited without a gitlab account or git skills

Questions:

  • Are there any plans to support signing into the wiki with the snowdrift SSO?
  • Are there any other places that link to the governance docs?
  • Is the information currently in the governance docs up-to-date in some way?
  • Should we archive the exact proposal texts (e.g. the sentence “We will introduce a secretary role” appears somewhere in a larger proposal), or keep documentation that is updated (e.g. there’s a list of current roles with their details), or both?
1 Appreciation
4

We do have SSO dreams, but in general infrastructure tasks have been set aside for now in the hopes that OSUOSL can take most of them over as we focus on items that have been dropped while putting out fires.

5

Not sure

It’s not too bad, but it needs work. We need to better establish our whole process and put it to use, updating as we go.

Not sure I follow this question.

At this point, I lean toward going with the governance repo.

UPDATE: I went and pinned the process post because that seemed appropriate at least so that looking at the #clear-the-path:project-management category has this pinned thing about making decisions on the forum. We can unpin when we decide how else to document.

6

It doesn’t have an answer. (I.e. it’s a generative question in the language of proposal forming (S3 pattern).)

The question is about these two things and whether it would be a good idea to do both, or whether one of them is more important, etc.:

  • Document the exact decisions made via consent. Examples:
    • “Introduce role X with responsibilities A, B, C, …”
    • “Remove role Y and replace it with [something]”
    • “Change »A team members« to »A team member« in the process for consent decisions”
  • Document the things that have been decided, but possibly in a different language, and change them to reflect the decisions made. Examples:
    • A complete list of roles and responsibilities
    • The process for consent decisions, updated to reflect both consent decisisions made about it (1, 2)

An obvious answer would be to document both; however, the second one might not always be possible, or it might require some effort if the documentation must be correct.

Another answer could be to always decide to do certain exact changes to the documentation, i.e. a git patch.

7

We should have some record of the decision (maybe just make a tag we apply to topics on the forum).

Each proposal should be determined case-by-case what the action is. In some cases, it’s updating our documentation. In the case of the proposal-consent process, we need new documentation since we had no prior version of that process.

8

I added a “proposal” tag and copied the specific poll process to the governance repo.

I want to end up with a reliable way to have a single-source-of-truth. I made some formatting updates (e.g. there should be only one # Title header in each post or document, the later ones should be ## Subheaders etc). That doesn’t need any consent, but we should have some way that updates to governance docs don’t just happen and slip by without notice.

So, I suppose these tensions should themselves go through the decision-making process.

9

I think something is still missing here. We need a single starting point that leads to each of the documented things team members should know about. So, maybe a place on the wiki that we add a link to the #proposal tag of the forum?

1 Appreciation