Expand RFC Pattern (#245) - Moving to Level 2

* Add 'Story' to RFC pattern
* Add BBC known instance of RFC pattern
* Add missing full stop
* Add Google Design Docs to RFC pattern
* Expand on waterfall risk of RFC pattern
* Expand on Solutions
* Expand on Resulting Context
* Add ADRs with note to Aliases
* Add RFC template

Co-authored-by: Sebastian Spier <[email protected]>
Co-authored-by: Johannes Tigges <[email protected]>

README.md

@@ -59,10 +59,10 @@ possible to either deploy the same service in independent environments with sepa
 * [Open Source Trumps InnerSource](https://github.com/InnerSourceCommons/InnerSourcePatterns/pull/46) - *People find the InnerSource project but, after all things are considered, even if the InnerSource component meets their needs, they still go with the open source component.*
 * [Start as Experiment](patterns/2-structured/start-as-experiment.md) - *An inner source initiative is considered but not started, because management is unsure about its outcome and therefore unwilling to commit to the investment.*
 * [Include Product Owners](https://github.com/InnerSourceCommons/InnerSourcePatterns/pull/71) - *Key Performance Indicators (KPIs) for Product Owners are primarily product focused, and don't consider areas such as collaborative development. This results in a lower level of engagement with inner source projects.*
+* [Transparent Cross-Team Decision Making using RFCs](patterns/2-structured/transparent-cross-team-decision-making-using-rfcs.md) - *InnerSource projects that want to achieve high participation rates and make the best possible decisions for everybody involved need to find ways to create participatory systems throughout the full software lifecycle. Publishing internal Requests for Comments (RFCs) documents allows for discussions early on in the design process, and increases the chances to build solutions with a high degree of commitment from all involved parties.*
 
 ### Maturity Level 1: Initial
 
-* [Transparent Cross-Team Decision Making using RFCs](patterns/1-initial/transparent-cross-team-decision-making-using-rfcs.md) - *InnerSource projects that want to achieve high participation rates and make the best possible decisions for everybody involved need to find ways to create participatory systems throughout the full software lifecycle. Publishing internal Requests for Comments (RFCs) documents allows for discussions early on in the design process, and increases the chances to build solutions with a high degree of commitment from all involved parties.*
 * [Modular Code](patterns/1-initial/modular-code.md) - *Management does not want to spend the extra resources needed to develop modular components and make them available in a visible repository for others to use.*
 * [Improve Findability](patterns/1-initial/improve-findability.md) - *People can't find the internally developed solutions that they need due to poor naming conventions. This causes frustration in finding inner source solutions and a reduction in code reuse.*
 * [Overcoming Project Management Time Pressures](patterns/1-initial/overcoming-project-management-time-pressures.md) - *Project management believes timeline pressure and commitments on feature content does not allow for developers to spend the time needed to develop shareable code and provide support.*

patterns/2-structured/templates/rfc.md

@@ -0,0 +1,91 @@
+# 000-Template
+
+- Feature Name: (fill me in with a unique ident, `my_awesome_feature`)
+- Start Date: (fill me in with today's date, YYYY-MM-DD)
+- Nominated owners: (Representatives of technical ownership areas affected by the RFC. This will often be tech leads, but they may delegate. RFCs cannot be accepted until all nominated owners have signed off.)
+
+## Summary
+
+One paragraph explanation of the feature.
+
+## Retrospective
+
+This section is essential to allow us to learn from the things we are implementing.
+
+_When is the retrospective?_
+
+[ ] Retro completed?
+
+(where/how it will be held, how can people get involved, where are the results?)
+
+## Motivation
+
+Why are we doing this? What use cases does it support? What is the expected outcome?
+
+## Guide-level explanation
+
+Explain the proposal as if it was already existing and you were teaching it to another engineer. That generally means:
+
+- Introducing new named concepts.
+- Explaining the feature largely in terms of examples.
+- Explaining how engineers should think about the feature. It should explain the impact as concretely as possible.
+- If applicable (eg code/architecture proposal), provide sample error messages, deprecation warnings, or migration guidance.
+- If applicable, describe the differences between teaching this to existing engineers and new engineers.
+
+For implementation-oriented RFCs, this section should focus on how contributors should think about the change, and give examples of its concrete impact. For policy/process RFCs, this section should provide an example-driven introduction to the policy/process, and explain its impact in concrete terms.
+
+## Reference-level explanation
+
+This is the technical portion of the RFC. Explain the design in sufficient detail that:
+
+- Its interaction with other features is clear.
+- It is reasonably clear how the feature would be implemented.
+- Corner cases are dissected by example.
+
+The section should return to the examples given in the previous section, and explain more fully how the detailed proposal makes those examples work.
+
+## Drawbacks
+
+Why should we _not_ do this?
+
+## Rationale and alternatives
+
+- Why is this design the best in the space of possible designs?
+- What other designs have been considered and what is the rationale for not choosing them?
+- What is the impact of not doing this?
+
+## Prior art
+
+Discuss prior art, both the good and the bad, in relation to this proposal.
+A few examples of what this can include are:
+
+- For language, library, tools etc: Does this feature exist in other places and what experience have their community had?
+- For community proposals: Is this done by some other community and what were their experiences with it?
+- For other teams: What lessons can we learn from what other communities have done here?
+- Papers: Are there any published papers or great posts that discuss this? If you have some relevant papers to refer to, this can serve as a more detailed theoretical background.
+
+This section is intended to encourage you as an author to think about the lessons from other places, provide readers of your RFC with a fuller picture.
+If there is no prior art, that is fine - your ideas are interesting to us whether they are brand new or if it is an adaptation from other places.
+
+## Unresolved questions
+
+- What parts of the design do you expect to resolve through the RFC process before this gets merged?
+- What parts of the design do you expect to resolve through the implementation of this feature before stabilization?
+- What related issues do you consider out of scope for this RFC that could be addressed in the future independently of the solution that comes out of this RFC?
+
+## Future possibilities
+
+Think about what the natural extension and evolution of your proposal would
+be and how it would affect the teams and projects as a whole in a holistic
+way. Try to use this section as a tool to more fully consider all possible
+interactions with the project and teams in your proposal.
+Also consider how the this all fits into the roadmap for the project
+and of the relevant sub-team.
+This is also a good place to "dump ideas", if they are out of scope for the
+RFC you are writing but otherwise related.
+If you have tried and cannot think of any future possibilities,
+you may simply state that you cannot think of anything.
+Note that having something written down in the future-possibilities section
+is not a reason to accept the current or a future RFC; such notes should be
+in the section on motivation or rationale in this or subsequent RFCs.
+The section merely provides additional information.

patterns/1-initial/transparent-cross-team-decision-making-using-rfcs.md → patterns/2-structured/transparent-cross-team-decision-making-using-rfcs.md

@@ -14,9 +14,13 @@ Discovering such disagreements or misunderstanding late in the process, e.g. onc
 
 For an InnerSource project this situation happens more frequently when the project is maintained by multiple teams in the company i.e. shared ownership.
 
-## Story (optional)
+## Story
 
-**TBD**
+A project, or application made up of multiple projects, is maintained by a number of different teams, with each team owning different areas of the project or application. These teams do make InnerSource contributions to each other's areas, but larger, cross-cutting changes are only ever driven by the teams' technical leads working together, or don't happen at all. This results in most engineers unable to effect large scale, cross-cutting change, reducing innovation and opportunities for collaboration.
+
+By implementing a process and template for RFCs, teams and individuals are empowered to propose large, cross-cutting changes via a transparent decision making process, with consultation across teams done asynchronously. This results in greater innovation, closer collaboration, and more knowledge spread. This is dependent on buy-in from all disciplines at all levels, and an environment of psychological safety so that people can openly propose and debate ideas.
+
+Like with any process, this must be continually improved upon. There may need to be changes to the RFC template or process to ensure it is inclusive, collaborative, and effective.
 
 ## Context
 
@@ -43,11 +47,20 @@ Important elements of the solution are:
 
 - a description of when to publish an RFC (and when not to)
 - a template for RFC documents
-- a well known process surrounding RFCs e.g.
-    - how to publish RFC and share it with all stakeholders
+    - should provoke RFC author to consider their proposal from multiple angles
+    - should prompt both high level accessible overview, and detailed in-depth explanation
+- a well known, lightweight process surrounding RFCs e.g.
+    - how to publish RFC and share it with all stakeholders (e.g. Slack, mailing list)
     - how to collect feedback for the RFC
     - how to work in the feedback
-    - how to move the RFC towards a conclusion or decision
+    - how to move the RFC towards a conclusion or decision (e.g. relevant nominated maintainers to sign off)
+    - appropriate tooling chosen (e.g. non-engineers may not have access to source control tools)
+- a commitment to iterate on the RFC template and process
+
+### Examples/templates
+
+- [Rust][rust] is a good Open Source example of RFC template and process, and has been the basis for many other RFC processes.
+- [Genericised BBC iPlayer & Sounds RFC template](templates/rfc.md), originally based on the [Rust][rust] template
 
 ## Resulting Context
 
@@ -57,14 +70,17 @@ Observable positive effects:
 
 - **democratization of the decision making process** for decisions that impact many teams (also offloading team leads from that burden)
 - **a open asynchronous communication method** that works well across multiple teams and geos
-- **terminology alignmen**t e.g. by spelling out our testing terminology such as “what is a system test?”
+- **empowers individuals and teams** to effect large scale change
+- **record of decisions made** for people to refer back to for context
+- **scales impact of experienced engineers** as they can contribute to solutions asynchronously and remotely, rather than needing to be present in a meeting
+- **terminology alignment** e.g. by spelling out our testing terminology such as “what is a system test?”
 - **process alignment** e.g. by spelling out the out-of-hours support process
 - **greater clarity of thought**, as writing an RFC makes the author challenge herself more than they would normally
 
 The RFC approach also has risk that we want to call out:
 
 - It doesn’t always work! e.g. some people might still argue against a decision that was already made via an RFC. However having the decision making process in writing is still beneficial in these scenarios, as you can point people to when and why a certain decision was made.
-- Writing up design proposals (architecture, protocols, etc) upfront has an element of upfront waterfall-like design to it that does not fit the iterative development approach that man development teams favor.
+- Writing up design proposals (architecture, protocols, etc) upfront has an element of waterfall-like design that does not fit the iterative development approach that many development teams favor. Remember: “Working software over comprehensive documentation” ([Agile Manifesto](https://agilemanifesto.org/)). The RFC process should be as lightweight as possible.
 - An RFC may become big and too unwieldy. This often shows in long comment threads and discussions surrounding it. In those situations we may decide to complement the RFC with synchronous communication such as a working group and in-person meetings. But time is still saved, as people can read the RFC before the meeting rather than having all the information shared during the meeting.
 
 ## Rationale
@@ -77,25 +93,31 @@ Also for decision making outside of pure software design decisions, transparent
 
 ## Known Instances
 
-- **Uber** - According to this blog post by Gergely Orosz: [Scaling Engineering Teams via Writing Things Down and Sharing - aka RFCs][uber].
+- **BBC iPlayer & Sounds** - As presented at the ISC Fall Summit 2020 [Using Internal RFCs to Enhance Collaboration][bbc].
 - **Europace** - As described in Open Organization: [Setting cross-team standards and best practices in the open][europace].
+- **Uber** - According to this blog post by Gergely Orosz: [Scaling Engineering Teams via Writing Things Down and Sharing - aka RFCs][uber].
+- **Google Design Docs** - As described in this blog post by Malte Ubl [Design Docs at Google][google]
 
 ## Status
 
-**Initial** - Created August/September 2020 in preparation for Tom Sadler’s talk “Using internal RFCs to enhance collaboration” at the [InnerSource Fall Summit 2020][innersource-fall-summit-2020]. This first version was written by Sebastian Spier, after an interview with Tom Sadler.
-
-**(future) Structured** - After the InnerSource Fall Summit 2020 we plan to extend this pattern with additional info based on Tom Sadler’s talk at the summit. With that we want to bring the pattern to maturity “Structured”.
+**Structured**
 
 ## Author(s)
 
 - Tom Sadler
 - Sebastian Spier
 
+## Aliases
+
+- [Design Docs][google]
+- Architecture Decision Record (ADRs) - Not necessarily a direct alias, as they can sometimes be used very differently e.g. RFCs for seeking input and building consensus, ADRs for recording decisions and implementation detail
+
 [requests-for-comments]: https://en.wikipedia.org/wiki/Request_for_Comments
 [30-years-of-rfcs]: https://www.rfc-editor.org/rfc/rfc2555.txt
 [rust]: https://github.com/rust-lang/rfcs
 [zeromq]: https://rfc.zeromq.org
 [uber]: https://blog.pragmaticengineer.com/scaling-engineering-teams-via-writing-things-down-rfcs/
 [europace]: https://github.com/open-organization/open-org-distributed-work-guide/blob/master/drostfromm-remote-first-through-openess.md#setting-cross-team-standards-and-best-practices-in-the-open
 [open-decision-framework]: https://www.redhat.com/en/about/press-releases/red-hat-releases-open-decision-framework-spur-transparent-and-inclusive-leadership
-[innersource-fall-summit-2020]: http://innersourcecommons.org/events/isc-fall-2020/
+[bbc]: https://www.youtube.com/watch?v=U6zlghE0HcE
+[google]: https://www.industrialempathy.com/posts/design-docs-at-google/