RFC Controversy Outline
An RFC skeleton covering the proposal, known risks, and open questions for a technically controversial change.
More from Writing
What you get
A precise RFC skeleton document in a format suitable for engineering teams, covering proposal, risks, and open questions, delivered as a text output.
Who it's for
- Engineering team leads proposing technical changes
- Software architects assessing trade-offs
- DevOps engineers evaluating migration paths
- Technical writers documenting system updates
- Product managers mitigating implementation risks
Use cases
- Proposing a technically controversial change to internal APIs
- Assessing the risks of replacing REST with GraphQL
- Documenting the trade-offs of a system migration
- Evaluating the feasibility of a new technical approach
- Mitigating the risks of a proposed technical change
- Creating a balanced technical proposal for stakeholders
FAQ
what should an rfc proposal include
An RFC proposal should include a clear summary, motivation, proposal details, known risks and mitigations, alternatives considered, and open questions. The document should be precise, blameless, and neutral, focusing on trade-offs rather than advocacy.
how do i structure an rfc document
A typical RFC document structure includes sections for Summary, Motivation, Proposal, Risks & Mitigations, Alternatives Considered, and Open Questions. This structure helps ensure that all necessary aspects of the proposal are addressed in a clear and organized manner.
what are some common risks in technical proposals
Common risks in technical proposals include team experience gaps, client caching behavior differences, and the need for additional governance or infrastructure. Identifying and addressing these risks is crucial for a successful proposal.
how long should an rfc proposal be
The length of an RFC proposal can vary, but it should be concise and to the point, focusing on the essential information and trade-offs. A well-structured proposal with clear sections can effectively communicate the necessary details without being overly lengthy.
Sample output
## Summary • Replace REST with GraphQL to reduce over-fetching and improve API flexibility • Apply the change across all internal APIs for consistency and simplicity • Potential benefits include improved performance and reduced data transfer • Requires significant updates to existing API infrastructure ## Motivation • Current REST APIs often result in over-fetching, leading to wasted bandwidth and slower performance • GraphQL allows clients to specify exactly what data they need, reducing unnecessary data transfer • Internal APIs are a good target for this change due to their high traffic and performance requirements • Updating APIs to use GraphQL can help improve overall system efficiency ## Proposal • Introduce GraphQL as the primary interface for all internal APIs • Develop a new schema governance process to manage GraphQL schema definitions • Update client libraries and frameworks to support GraphQL queries and caching • Establish a timeline for migrating existing REST APIs to GraphQL ## Risks & Mitigations • Low team experience with GraphQL may lead to implementation delays or errors • Client caching behavior may need to be revised to work effectively with GraphQL • Undefined schema governance may lead to inconsistencies or conflicts between APIs • Provide training and support for team members to learn GraphQL and its best practices ## Alternatives Considered • Sticking with REST and optimizing existing APIs for better performance • Using a hybrid approach that combines REST and GraphQL for different APIs • Implementing a different query language or API paradigm, such as gRPC • Gradually introducing GraphQL for new APIs while leaving existing ones on REST ## Open Questions • How will schema governance be managed and enforced across different teams and APIs • What are the specific caching requirements for GraphQL APIs, and how will they be implemented • What is the expected timeline and resource allocation for completing the migration to GraphQL • How will the success of the GraphQL migration be measured, and what are the key performance indicators
Last updated: 2026-06-28