After being exposed to an early release of Facilitating Software Architecture ebook from Andrew Harmel-Law at O’reilly edition, I noticed it echoes very well what we were proposing for here, namely:

• Build an ecosystem by shaping compelling knowledge base and fostering cross-collaboration
• Support inner-source model by ensuring transparency and trust between stakeholders
• Empower teams by ensuring they drive their own technical choices
• Streamline architecture decision making process by promoting a methodology
• Enforce pragmatism by setting up lightweight but efficient mechanism

Decision Process

The distinction between making and taking a decision is an important one and is worth repeating:

• Option making - pulling together a set of options to choose from
• Decision taking - considering and then selecting an option

Architecture Advice Process

Architecture Advice Process is a mechanism that allows organizations to decentralize the architecture decision-making. Indeed, instead of relying on a few architects solely accountable and responsible for the architecture, it fosters the involvement of all development stakeholders in the decision-making process. Anyone can make an architectural decision provided that people who might be impacted by the decision and the experts in that area are consulted.

― Andrew Harmel-Law

The key factor in a decision process’s decentralization with regards to decision-rights is the number of people who are de-facto entitled to initiate, and then contribute to the taking of decisions. The greater the number, and the deeper their involvement, the greater the decentralization. The decision maker/taker - this is the person who initiates the process because they have a need which they need to take a decision on; those offering the advice - these are the people who represent the affected parties and those with expertise.
Advice powers up and empowers decision-takers.

― Andrew Harmel-Law

Architecture Decision Record

Capture significant decisions regarding technical architecture while materializing context, spelling out decision making and stressing consequences. Those documents obey a dedicated format and are gathered in a dedicated library everyone can access for exploration, time traveling or on-boarding.

ADR - Reader-first

Adopt the reader point of view, surfacing compelling information at the top:

• I can check metadata section and decide to leave if ADR status is not the one I am interested in
• If status is accepted, I can take note of the decision
• To better understand decision, I can look at context section
• I can refine my understanding by parsing options decision was made of
• Eventually, I can read over consequences to better grasp pros and cons for every options
• Ultimately, I can dive in underlying discussion process

By nature, lightweight. Ideally, using template, but teams can used their own if they prefer.

Implementation Proposal - a GitHub-based approach

ADR hub as issue

Leverage built-in filters for smart exploration:

• ADR status backed by milestone
• ADR metadata by labels (e.g., Topic, Team, Tech)
• ADR author by assignee.

ADR insights

• Advice Process to reference matching discussion space
• Spikes or Materials to share any related work
• Links to provide any relevant documentation
• Closing comment linking to shaped ADR.

Forum as GitHub discussion

Advice process

Leverage built-in filters for smart exploration:

• Title matches ADR issue
• Metadata use labels (ID, Topic, Team, Tech)
• Decision maker as discussion owner
• Thumbnail to count participants
• Interactions counter to gauge activity

Advice

• Context - expose what the discussion will be about
• Those affected by the decision - dynamic listing of who we’d like advice about
• People with expertise - dynamic listing of who we’d like advice about

Advice ranking

Assemble

Dedicated template to summarize assemble topics & engagement

Assemble discussion

• Act as meeting agenda
• Host or bootstrap related technical discussion
• Informal discussion staying in Teams, provide a curated history for readers to parse
• Benefit from labelling to ease navigation
• Allow for subscription

Assemble, why?

• TL; DR. Why not. :sweat_smile:

• Strong reference to Avengers (for those sleeping) AAP underlying paradigm is to empower people.

• We can then easily quote Peter Parker uncle with its famous with great powers come great responsibilities to ensure people do not forget that even if they are granted the ability to own a decision making cycle, they have to obey the impacted/expert rule as well as to sign in the accountability side of the coin…

• At this stage, one can argue the metaphor not being totally inclusive. We want everyone participating, not only super-heroes, so we have to ensure no-ones being excluded because of this. Perfect timing to quote not All Heroes Wear Capes. Underlying AAP postulate once again, where everyone is empowered not only the legacy/shiny/noisy individuals.

• And because we walk the real world. No heroes will come and save the entire company for the bad design villain.
  We all are there, without capes, but sleeves rolled up..

• Last but no least, calling for a meeting beautifully translates into ADRangers, Assemble!. I do think having the ability to shout those words is something one can’t miss if he is given the opportunity to do so. Like having opportunity to hold Star Wars Day May, the 4th but picking another date…

Query

Assuming I recently heard about Aspire and would like to learn more about the underlying stack. What should I start with?

Leveraging built-in query engine, I can surface meaningful information such as:

• There is an on-going discussion that involves Aspire. I should read it and maybe engage with. It will give me valuable insights such as involved teams and experts, and so on.
• Aspire was discussed or show-cased during Assemble #000. I may have a look at meeting notes for shared information.
• A spike has been shared I can probably exercise with. Let’s see if there is some repository I can clone or some technical documentation I can explore.
• @RVR06 seems to be deeply involved as it bootstraps all above entries. I should probably ping him through Teams.