Add: initial pattern document architecture decisions #773
Conversation
rossbachp
requested review from
lenucksi,
NewMexicoKid,
cewilliams,
spier,
robtuley and
yuhattor
as code owners
|
💖 Thanks for opening this pull request! 💖 The InnerSource Commons community really appreciates your time and effort to contribute to the project. Please make sure you have read our Contributing Guidelines. If you are submitting a new pattern, the following things will help get your pull request across the finish line! 🏁
This project has a small number of maintainers, volunteering their time to this project. So please be patient and we will get back to you as soon as we can. If we don't acknowledge this pull request after 7 days, feel free to chat to us about it in our Slack workspace. |
spier
added
1-initial
|
Many thanks sebastian, to fix the typos:) |
There was a problem hiding this comment.
Great job with this pattern draft @rossbachp!
I left some inline comments. I will immediately resolve the trivial fixes myself, to save you some work.
Once you are done with reviewing the remaining feedback, we could already merge this actually!
If you want to spend a bit more time in this PR, the only larger area where I see a potential for improvement:
The Story section in your pattern is great! It provides specific examples of what the Solution section is describing, in a chronological order of how this might have take place at a specific org.
I am wondering if merging the content into the Solution section would make it easier for readers to understand
a) what are the building blocks required to establish the ADR pattern in a project/org
b) how using an ADR process might "feel like in practice for a given team" (the content of your Story
Thanks again for sharing this amazing first draft of a pattern with us!
Looking forward to working with you on this.
There was a problem hiding this comment.
Great job with the latest iteration @rossbachp!
I left one more comment related to the Context section, which I must have missed in the previous version.
Once you reviewed that we can already integrate this pattern into our repo, to get more eyeballs onto it.
|
|
||
| For an InnerSource project this situation happens more frequently when the project is maintained by multiple teams in the company i.e. shared ownership. | ||
|
|
||
| ## Context |
There was a problem hiding this comment.
FYI I moved this section to the top. We set the Context early one, as it helps the readers to decide "Do I have this same particular situation?"
More details about the questions that the Context section should answer:
- Where does the problem exist?
- What are the pre-conditions? Unchangeable before the solution goes into place.
- Applicability of the pattern for other readers: "Do I have this same particular situation?"
Some of the bullets below match that goal alrready.
However some others, at least the last 3 bullets below, rather seem to describe the solution.
Could you double-check if the current points in this Context section are focused on the questions above?
There was a problem hiding this comment.
Nice catch!
I commit a reformulation of the points :)
There was a problem hiding this comment.
Thanks!
Some of the Context bullets still don't clearly answer the "where does the problem exist" question in my mind.
However I am opting to merge this PR as is, and fix this in future PRs.
Will leave this comment open, so that we can find it again if needed.
Current Context bullets that are not clearly connected to the "where does the problem exist" question are:
- Decisions need preparation
- Continuous definition of technical debt
- Input from various types of users
Most of them seem more like statements that would be true for any organization i.e. they don't help the reader to decide whether the problem/pattern applies to them.
README.md
Outdated
| @@ -92,6 +92,7 @@ Our mission | |||
| * [InnerSource Ambassadors](/patterns/1-initial/innersource-ambassador.md) - *When driving InnerSource adoption through a large, decentralized organization it is hard to understand and address the local challenges that come up in different departments and regions. Local volunteers, called InnerSource Ambassadors, provide localized support by promoting InnerSource principles and acting as a communication bridge between their teams and the ISPO.* | |||
| * [Circle Communities](/patterns/1-initial/circle-communities.md) - *InnerSource adoption is slow in organizations due to limited understanding, engagement, and contextual relevance. Circle Communities address this by fostering synchronous conversations that build connections, close knowledge gaps, and cultivate collaboration and continuous learning.* | |||
| * [Internal Developer Platform](/patterns/1-initial/internal-developer-platform.md) - *As InnerSource adoption increases throughout an organisation, it is not unusual that project teams start to face inefficiencies in scaling their efforts due to fragmented tooling, environments, and workflows. An Internal Developer Platform (IDP) provides a way to tackle this type of challenges through a centralized, self-service system that standardizes development environments and integrates tools to enhance consistency, collaboration, and developer productivity.* | |||
| * [Document Architecture Decisions](/patterns/1-initial/document-architecture-decisions.md) - *InnerSource contributors often face challenges in grasping the system's design rationale, which can result in misalignment between maintainers, contributors, and stakeholders—potentially discouraging participation. To enhance decision-making and transparency, we recommend capturing architecture decisions and their consequences in a lightweight, accessible format to streamline onboarding, clarify decisions, and support long-term project sustainability.* | |||
There was a problem hiding this comment.
Great job with the quick iterations @rossbachp! Great way to collaborate.
While Patlet and Context could still be improved, I am opting to just merge and move forward. We can still improve this pattern in future PRs, as we integrate further Known Instances etc.
Will leave some comments open, so that I have a chance to remember these points later. :)
Thank you so much for your contribution!
|
|
||
| For an InnerSource project this situation happens more frequently when the project is maintained by multiple teams in the company i.e. shared ownership. | ||
|
|
||
| ## Context |
There was a problem hiding this comment.
Thanks!
Some of the Context bullets still don't clearly answer the "where does the problem exist" question in my mind.
However I am opting to merge this PR as is, and fix this in future PRs.
Will leave this comment open, so that we can find it again if needed.
Current Context bullets that are not clearly connected to the "where does the problem exist" question are:
- Decisions need preparation
- Continuous definition of technical debt
- Input from various types of users
Most of them seem more like statements that would be true for any organization i.e. they don't help the reader to decide whether the problem/pattern applies to them.
|
|
||
| ## Patlet | ||
|
|
||
| InnerSource contributors often face challenges in grasping the system's design rationale, which can result in misalignment between maintainers, contributors, and stakeholders — potentially discouraging participation. To enhance decision-making and transparency, we recommend capturing architecture decisions and their consequences in a lightweight, accessible format to streamline onboarding, clarify decisions, and support long-term project sustainability. |
There was a problem hiding this comment.
I feel we could make the 2nd sentence more clear.
Right now it is of the form:
<intended benefit>, <approach>, <more intended benefits>
However I cannot come up with a better version right now either, therefore let's leave it as is for now.
I am leaving this comment open.
|
|
After an insightful discussion with Christoph Kappel and Sebastian Spier, I’d like to open up a broader conversation about documenting architectural decisions and technical debt records.
You can find more details in the DeciCollab project.
Looking forward to your thoughts and feedback!
Best regards,
Peter