A meta-discussion, about Discussions

[0xApotheosis]

Context

Engineering discussions and decisions at ShapeShift often take place in a synchronous and ephemeral way, requiring all would-be participants to be present at the time of the discussion (a Discord call, or similar).

GitHub Discussions offer a way to invite feedback and discussion on important decisions and ideas. From the best practice guide:

You can use GitHub Discussions to discuss big picture ideas, brainstorm, and spike out a project's specific details before committing it to an issue

Proposed usage

• Use GitHub Discussions to record discussions relating to engineering when they are important, long-running, and/or would likely benefit from the input of additional contributors
• If a meeting is held on a topic worthy of a Discussion, add any resulting context or decisions to the corresponding Discussion (or create a new one!)
• When communicating, use low-context communication. That is, assume the reader has little context about the subject matter. Concretely, the communication should contain all the needed context for the subject/idea to be understood.

Getting oneself in a low context frame of mind can be useful. Start by assuming that recipients of your communication do not know anything about the topic at hand, and wish to learn as much as possible in as little time as possible.

Benefits

Recording discussions in this manner would allow ShapeShift:

• to better persist decisions that are made and the reasoning behind them
• facilitate an asynchronous contribution workflow spanning timezones and teams

Considerations

• We do not want to add unnecessary friction to discussions and ideation - too much friction a process is abandoned. If a synchronous chat is more appropriate, do that. If information about the decision will benefit others, post the decision and its supporting reasoning into a Discussion thread for others to contribute to, or understand retrospectively.

• Discussions are repo-specific. We do have the option of team discussions, which are repo-agnostic, though this prohibits our broader community members from contributing to discussions.

Why not just use GitHub issues?

GitHub recommends "... to use discussions to brainstorm with your team, and eventually move the conversation to an issue when you are ready to scope out the work".

Issues are the concrete instantiation of the outcome of the discussion (they can also be created directly from Discussion comments.

Resources

• GitHub discussions best practices

[0xdef1cafe]

@0xApotheosis thank you for raising this, in writing!

i'm fully in support of this, and like that you've outlined the downfalls too. we don't want to be rigid with this as a hard process requirement, but lean into this idea and slowly adopt it. in my opinion, unless things are written down, they didn't really happen.

i like the distinction that discussions are for ideas, issues are for well defined work ready to be done.

@natven @majorhayes please keep this at the front of mind when architecting things, even if the discussions is initially a dumping ground for links/diagrams/POC PRs, it gets us going in the right direction.

as an initial thought of a topic that needs this kind of discussion - we have a few feature requests from product that will turn the asset service from static build time data to supporting dynamic run time data, and we shouldn't jump to a solution before figuring out architecture and impacts. i added the needs architecture label to issues that are affected and this could be a good starting point.

regarding the scoping of this to repo/teams, let's just figure it out as we go. maybe it would be nice if it was org level if we can, as our discussions will mostly span multiple repos.

[gomesalexandre]

Thanks @0xApotheosis for this.
I agree with the benefits and think GitHub Discussions are a great way for us to have information saved and continued in an asynchronous manner rather than it being lost after e.g meetings.

The low-context communication in particular is a really interesting point you're bringing. It is one of the keys to async collaboration, and a writing exercise we should get comfortable with.
Bounties are a great inspiration for this way of communicating. They are well-crafted issues that suppose 0 previous knowledge, and contain everything you need to either start working on something or ask additional questions one might have.

And as mentioned by @0xdef1cafe, repo-specific Discussions might be the best in some cases, while org-level Discussions could potentially be equally as interesting in others.
Taking the very first needs architecture issue as an example, it spans across both asset-service and web projects. IMO, such kind of discussions would live in an org-level Discussion.

[cjthompson]

What works best for me, personally, is having live discussions with people, however, I completely agree that someone in that conversation should document in a Discussion what was talked about in the meeting.

Further, once specific decisions are made, I'd like to see us leveraging the docs repo to host the record of final decisions so that we don't have complete reliance on GitHub as a source of record.