Maintain Decision Records

A complex release engineering system is built from decisions that have consequential effects in and out of the system. Most of these decisions feel logical while others feel counterintuitive.

It's foolish to rely on human memory as a way to make sure these decisions are transmitted across the team, notwithstanding that teams change over time as well. Learning from a senior engineer is appropriate for skill development, but isn't a good substitute for gaining context around decisions taken in the architecture and design of the Release Engineering system.

And over time, as teams make updates to the process and workflow, it's important to preserve the knowledge for future or absent engineers. It also provides a snapshot of where the philosophy of the architecture stands at any given point.

Decision records help with this problem. A bit of bookkeeping upfront yields tangible benefits. The team records any important decision made in the team. This allows the team to remember why a decision was made and keep the context in mind when reversing it.

It also establishes a lightweight way to discuss a matter in a manner that's written, similar to how RFCs have been adopted and used in many open source projects. While RFCs are proposals, decision records can be proposed, or recorded as a result of a decision in a meeting.

There are various different styles and templates to use. You'll want to adapt it to your team's needs but anything as extensive as RFCs, Python Enhancement Proposals to a lightweight approach such as Architectural Decision Records (ADRs) could work. Begin with a lightweight approach and only extend to include more metadata as needed.