Better approach to discussing and documenting Engineering Discoveries in Secure section
Problem to solve
While processing the Engineering Discovery issues (example), I had a feeling that communication about various aspects of the UX and implementation is pretty scattered across the issue comments. It's often necessary to scan through the entire comments thread and be cautious to avoid missing the important details.
Intended users
Initially, gitlab-org/gitlab-ee~4116714 stage team
Further details
We already have some practices to optimize the process of communication in the issues:
- development log's decisions section (example)
- communication guideline to regularly update the issue description (item
9.
in issues guidelines)
This issue aims to improve these approaches even further.
Proposal
To discuss together if this is really a problem for the gitlab-org/gitlab-ee~4116714 stage. And if yes, what practices and tools can we leverage in order to mitigate it.
Potential solutions
- the approach we're currently using during Secure Brainstorming sessions (internal): discuss the feature from UX and Engineering perspective in a recorded video call, then document the outcome in the related issue
- pros: intense discussion happens during sync session, question get answered much quicker and with less noise; better opportunities for structured documentation of the outcome
- cons: has a significant portion of synchronous communication by design
- possibly upcoming pinning of issue comments
- resolving discussions in issues to make them less noisy
What does success look like, and how can we measure that?
- Engineering Discover issues in gitlab-org/gitlab-ee~4116714 always have the Decisions with the discovery outcome clearly defined as a list of steps that are straightforward to implement
- It's enough information in the issue description to get the full picture for a team member who is new to the discovery subject