├── .gitignore ├── 0000-template.md ├── LICENSE-APACHE ├── LICENSE-MIT ├── README.md └── text └── 0001-using_rfcs.md /.gitignore: -------------------------------------------------------------------------------- 1 | *~ 2 | -------------------------------------------------------------------------------- /0000-template.md: -------------------------------------------------------------------------------- 1 | --- 2 | RFC: 3 | Title: TODO_TITLE 4 | Start: TODO_START 5 | PR: 6 | --- 7 | 8 | # TODO_TITLE 9 | 10 | *SEE `README.md` for how to submit a new RFC, and `0001-using_rfcs.md` for why we are using an RFC process. Delete this line when done.* 11 | 12 | # Summary 13 | This is a one paragraph explanation of the issue and the proposal. 14 | 15 | # Motivation 16 | This section details why we are doing something, what use cases it supports, and what we expect the outcome to be. 17 | 18 | # Guide Implementation 19 | This is a high level overview of the process. In this section, explain the proposal as if it was already used at your company and you were teaching it to a new engineer. That means you're probably including 20 | * Introduction of new named concepts 21 | * Explain things in terms of examples 22 | * Explain the impact and how you want engineers to approach the feature and its goals 23 | * If applicable, provide sample errors / warnings / or migration guidance 24 | * If applicable, describe the differences required teaching this to new engineers vs existing engineers 25 | 26 | # Reference Implementation 27 | This section provides space for deep technical details as required in the RFC. You need to hit on the following points in your reference implementation: 28 | * It's interaction with other features / infrastructure 29 | * It is reasonably clear how this would be implemented 30 | * Corner cases are addressed through example 31 | You can (and should) expand on the examples you used in the Guide Implementation and provide additional context. 32 | 33 | # Drawbacks 34 | You should explain why we _wouldn't_ do this. There is a cost associated with these changes, and while there wouldn't be an RFC if the benefits didn't outweigh the drawbacks, your readers might not know all of the tradeoffs being made. 35 | 36 | # Rationale / Alternatives 37 | You need to answer why this design is the right design. To do so, you need to understand all of the possible alternatives. You should list alternate designs and ideas and why they weren't considered for the solution. This ensures due diligence has been done on the proposal. 38 | 39 | # Unresolved Questions 40 | You should gather any open questions and either list them in the document (folks often use markdown quoting) or add them to this section at the end of the document. If you want to mark unresolved options inline 41 | 42 | > **Open Question:** this is an open question 43 | 44 | Is the common format used. The quote and bold combination (plus its indent) makes it easy to spot when reading through the document. 45 | -------------------------------------------------------------------------------- /LICENSE-APACHE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /LICENSE-MIT: -------------------------------------------------------------------------------- 1 | Permission is hereby granted, free of charge, to any 2 | person obtaining a copy of this software and associated 3 | documentation files (the "Software"), to deal in the 4 | Software without restriction, including without 5 | limitation the rights to use, copy, modify, merge, 6 | publish, distribute, sublicense, and/or sell copies of 7 | the Software, and to permit persons to whom the Software 8 | is furnished to do so, subject to the following 9 | conditions: 10 | 11 | The above copyright notice and this permission notice 12 | shall be included in all copies or substantial portions 13 | of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF 16 | ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED 17 | TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 18 | PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT 19 | SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 20 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 21 | OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR 22 | IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 23 | DEALINGS IN THE SOFTWARE. 24 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # RFCs 2 | ``` 3 | These standards (or lack of them) are stated explicitly for two reasons. 4 | First, there is a tendency to view a written statement as ipso facto 5 | authoritative, and we hope to promote the exchange and discussion of 6 | considerably less than authoritative ideas. Second, there is a natural 7 | hesitancy to publish something unpolished, and we hope to ease this 8 | inhibition. 9 | -- Stephen Crocker RFC3 (https://tools.ietf.org/html/rfc3) 10 | ``` 11 | 12 | RFCs are an effective way for an engineering organization to manage both historical and planned changes. With curation, your RFC archive tells the story of your company's technology and thought process. We believe in an open and honest dialog between all engineers. Because of this, we've embraced the Request for Comments system. 13 | 14 | 1. Any person at the company can create a Request for Comment and have it included in this series 15 | 2. These RFCs should always choose "timely" over "perfect" 16 | 3. These are not authoritative ideas (what's authoritative is what's in the code) 17 | 18 | Since the inception of the RFC process modern tools (hi git!) have made it possible to build a rich RFC process with minimal effort. Github, Bitbucket, Gitlab, and other collaborative repositories all have code commenting and review tools, capable of capturing the discussion surrounding RFCs, and which RFCs are being strongly championed by the company. 19 | 20 | Many software changes, including bug fixes and documentation improvements can be implemented and reviewed via the normal git pull request workflow without ever touching this process. However, we do ask that bigger requests and ideas follow a bit of formality, especially when you are thinking about changes that impact other engineers elsewhere in the company. By creating an RFC, you're guaranteed that impacted folks have an adequate heads-up on the changes. 21 | 22 | Please refer to [RFC1](https://github.com/LeadSV/rfc/blob/master/text/0001-using_rfcs.md) "Using RFCs" for a detailed explanation of why RFCs are important and how to contribute your own RFC to this series. 23 | 24 | # The Process 25 | * Fork this repository so that you have a copy 26 | * Copy the template file: `cp 0000-template.md text/0000-my_feature.md` 27 | * `Are You an Open Source Project?` then don't forget to ask RFCs to contain a license (they'll often contain code, after all) 28 | * Fill in the RFC. Put thought into the sections, but remember that **timely is more important than perfect** 29 | * Submit a pull request. Be prepared to revise it as folks weigh in. 30 | * Help drive consensus on the RFC. Work to understand concerns. 31 | * Be willing to update the RFC as yours (and the company's) understanding evolves 32 | * Assist in wrapping up discussions when a final call for comments is made 33 | 34 | # What An Approved RFC Means 35 | RFC approval means that the RFC will be assigned an ID and added to the series. RFCs may not be added to the series for reasons such as: 36 | * There is no clear consensus, and we are concerned the publication would be seen as authoritative 37 | * You have informed the domain owner that you do not wish for the RFC to be published 38 | * The RFC is not complete, making consensus difficult 39 | 40 | If the RFC is not approved for publication, the domain owner responsible for editing RFCs will provide clear and detailed feedback regarding why the RFC wasn't published. Your RFC will continue to exist in the code review history and available in searches. 41 | 42 | A published RFC ensures that other teams are made aware of the document. 43 | 44 | Modifications to "active" RFCs can be done in follow-up pull requests. We strive to write each RFC that refers to architecture in a manner that it will reflect the final design; but the nature of the process means that we cannot expect every merged RFC to actually reflect what the end result will be at the time of release. 45 | 46 | In general, once published, RFCs should not be substantially changed. Only very minor changes should be submitted as amendments. More substantial changes should be new RFCs, with a link added to the original RFC. 47 | 48 | # Isn't Good Enough? 49 | If you have a great system that already helps you capture "why" and is good at democratizing ideas, you don't need this! If you're looking for something that has advantages over tools such as slack, wikis, and documents this may be a strong alternative. 50 | 51 | # Acknowledgments / License 52 | This work was inspired by the [Rust RFC Process](https://github.com/rust-lang/rfcs) and IETF [RFC3](https://tools.ietf.org/html/rfc3) "Documentation Conventions". 53 | 54 | This repository text is available under both the Apache-2.0 and MIT license. 55 | 56 | Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0) 57 | MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT) 58 | -------------------------------------------------------------------------------- /text/0001-using_rfcs.md: -------------------------------------------------------------------------------- 1 | --- 2 | RFC: 1 3 | Title: Using RFCs 4 | Start: 9/3/2017 5 | PR: 0 6 | --- 7 | 8 | # Using RFCs 9 | 10 | # Summary 11 | This is a proposal to use RFCs in engineering. The "Request for Comments" system is used by several successful open source groups, and provides a framework for managing complex change and its documentation. Not everything needs an RFC, but since this can slow a company down, the proposal itself deserves an RFC to explain the rationale and reasoning. 12 | 13 | # Motivation 14 | Larger changes, while still reversible, require some amount of documentation as to why the decisions were made and the technical climate at the time the idea was proposed. Historically, these live in wikis or alternative documentation systems. These locations are either difficult to search, too far removed from the code, or are rarely seen as a source of truth. 15 | 16 | This solution proposes a documentation system that lives in code, uses plain text for authoring, and takes advantage of existing git collaboration tools in order to edit, maintain, and build consensus on code ideas that impact all of engineering. It is based on the RFC process as designed by the IETF and later adapted for open source projects. 17 | 18 | # Guide Implementation 19 | To make sure you've hit on all major parts of an RFC, this RFC can serve as a reference model. 20 | 21 | ## Creating a new RFC 22 | Creating a new RFC should be something you start as soon as it feels like the work is substantial and worth getting additional opinions on. You can start an RFC by forking this repository and copying the template file to a new file in the `text/` directory: `cp 0000-template.md text/0000-my_feature_name.md`, replacing `my_feature_name` with a shortened name for your feature or proposal. You'll be given a simple markdown document, for which you can edit the sections and start your proposal. 23 | 24 | ## Getting Feedback Pre-Pull Request 25 | The beauty of git is that you can have your RFC in your own local branch, at an accessible URL, which you can share to other individuals to get feedback. While we won't be prescriptive on who you should be reaching out to at this stage, testing your ideas and assumptions with several senior engineers can help work out any large issues. If you don't have great solutions yet, that's okay! Just mark the areas as still open and needing input. 26 | 27 | ## The Pull Request 28 | When you feel you're ready to get more feedback beyond your immediate peers, it's time to make a pull request. Most git tools have a way to submit a pull request to the upstream repository. [For example, here's GitHub's instructions](https://help.github.com/articles/creating-a-pull-request/), and [here is GitLab's process](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html). With a formal pull request, folks can comment on the pull request, suggest changes, and have discussions about the issue all in your company's code management tool of choice. More importantly, all of these discussions are captured and will live on in the pull request's history. 29 | 30 | ## Manage Feedback 31 | As more eyes look at your RFC, they'll have their own valuable thoughts and opinions to share. As the creator of the RFC, it's generally good to address feedback and if necessary, make changes to the RFC. If you have a meeting in which the RFC is discussed, be sure to capture the notes and share them in the RFC's pull request as a comment. After some amount of time, the folks closest to the domain at the company will ask that all final comments are submitted. 32 | 33 | ## Final Feedback 34 | To avoid discussion going in circles forever, an owner in the domain related to your RFC will ask for "final comments". At that point, the discussion will wrap up, and the group accountable for the domain related to your RFC will determine if this RFC proposal needs to be widely distributed. If distribution of the RFC is decided, the pull request will be accepted and the RFC given a numeric ID. If a RFC was not chosen to be distributed, that request and the RFC document continue to exist in your collaborative repository's ticket system, capturing the rationale and explanation. 35 | 36 | > **Open Question:** Who can declare that an RFC is entering its Final Feedback phase? This can be a senior engineer, a scrum master, or other individual passionate about the process. They don't have to be a voting member for the RFC, just a facilitator. 37 | 38 | > **Open Question:** What is the decision process in your company for resolving an RFC? It could be a meeting or an up/down vote by N individuals in your company. Whatever you decide, it should be consistent. 39 | 40 | ## Adoption 41 | When an RFC is chosen for distribution, it will be given a numeric ID corresponding with the next sequence in the `/text` directory (This is why your file was `0000-my_feature_name` originally). While this does not guarantee the opinion is widely adopted, it does ensure that it has the support of the individuals accountable for the domain relevant to the RFC. 42 | 43 | If an RFC is not chosen for distribution, clear explanations will be provided by the domain owner and the pull request closed. This does not prevent the implementation of the idea, but the decision on an RFC carries significant weight. Remember, RFCs exist to inform and share information and intent. 44 | 45 | # Reference Implementation 46 | `0000-template.md` contains the minimum template needed for an effective RFC process. An RFC pull request document must meet the folowing criteria: 47 | * Adds to `text/` with a filename `0000-my_feature_name.md` where `my_feature_name` maps to the feature name in the header of the RFC 48 | * The RFC pull request contains a single file change that is the `0000-my_feature_name.md` file 49 | * The RFC file contains the following sections: Summary, Motivation, Guide, Reference Implementation, Drawbacks, Alternatives 50 | 51 | > **Open Question:** You will need to expand the reference implementation with specific git commands you want used, especially if your company has a process around rebasing / merging upstream. 52 | 53 | # Drawbacks 54 | **Time:** A common cited problem for an RFC process is the time investment asked of every participating engineer. This is in error, as the time required to create an RFC is ultimately spent in several other ways stemming from a lack of consensus or documentation. A proposal for an RFC has the highest ROI at the beginning of the process, not the end. In situations where there is already substantial buy-in from domain owners, the RFC is a lightweight process of recording what was already agreed upon. In situations where there is disagreement, then this time spent in the RFC process becomes time well spent. 55 | 56 | **Owners:** Ownership is something difficult for engineering organizations to talk about. It requires the engineering organization to agree outright that one or more individuals are operating in the best interest of a domain and will invest the time ensuring their domain remains well maintained. However, these owners already exist; they are the folks engineers turn to with questions. To offset the obligation of being an owner, ownership can be added to an individuals engineering expectations and factored into any leverage / impact criteria for their role. 57 | 58 | # Rationale / Alternatives 59 | ## Decision Bodies 60 | RFCs are a better solution than forming an Architecture Council. The move to create an Architecture Council forms when there is no longer a way to create consensus around a topic. Unfortunately, AC meetings are often reduced to debating semantics and rarely making decisions regarding proposed changes to the domain. Another common problem with ACs is they often lack a holistic view of the domains in engineering. Without the right individuals representing the needs of the domain, the best decisions cannot be made. RFCs avoid this process. Each RFC naturally drives towards a decision (and a decision is required on every RFC). Every RFC can be handled asynchronously, avoiding the challenges associated with running a regular meeting with senior engineers. 61 | 62 | RFCs are a more comprehensive solution than [Architecture Decision Records (ADRs)](https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records) and [whydocs](https://web.archive.org/web/20161119073912/https://medium.com/@jakob/a-better-framework-for-status-5c3dde887aa5). While ADRs and whydocs can effectively capture decisions being made during the development phase of software, they fail to capture ideas and intent. Why we **don't** do things is equally important to why we **do**, necessitating a more complete process. 63 | 64 | ## Documentation Systems 65 | RFCs are superior to wikis. While wikis often have better search facilities, wiki pages do not easily foster the discussion needed around major engineering topics. Wikis lie outside of an engineer's normal workflow and tools, making them less visible to the engineering organization. RFCs are a naturally better fit for the engineering workflow, leveraging GitHub/GitLab/BitBucket/etc and their native review and discussion tools. 66 | 67 | RFCs are a better alternative than document cloud options. While document clouds have better discussion tools than wikis, the ability to locate documents is restricted to the search facilities and sharing permissions available in the document cloud. For example, items shared with a limited subset of engineers are unlikely to receive holistic review. Further, when the document author leaves the company, the decisions risk being lost unless the owner is migrated. RFCs avoid this by living as code in a git repository, owned by the engineering organization as a whole. 68 | 69 | # Unresolved Questions 70 | Unresolved Questions are marked inline in the following format: 71 | 72 | > **Open Question:** topic 73 | 74 | These questions remain open and require either textual amendment to define the operating rules of your unique RFC process, or a supplemental RFC proposing adaptations that build upon this idea. 75 | --------------------------------------------------------------------------------