Advanced
Documentation Types
#rfc
#design-doc
#writing
#architecture
RFC & Design Documents
5 exercises — RFC openings, alternatives considered, trade-offs, open questions, and implementation plans. The structure and vocabulary that drives technical consensus.
0 / 45 completed
1 / 45
An engineer is writing the opening section of an RFC. Which opening best serves the document's purpose?
An effective RFC opening must answer three questions in the first paragraph:
1. What is being proposed? "replacing per-service Redis instances with a shared Redis Cluster"
2. Why? "reduce cost by ~$4,200/month and eliminate 3 on-call failure modes"
3. What is the constraint/success criterion? "while maintaining <5ms p99 cache latency"
This matters because senior engineers and stakeholders will read the title + first paragraph and decide whether to read further. If your opening is vague, persuasive, or personal-opinion-heavy, you lose credibility immediately.
RFC opening anti-patterns:
• "The author believes…" — RFCs make proposals, not personal arguments
• "As you all know…" — assumes shared context, signals lazy writing
• "Please read and let me know" — RFCs drive decisions, not open polls
• No numbers — quantify the problem whenever possible
Standard RFC sections:
• Abstract / Summary
• Motivation / Problem Statement
• Proposal / Design
• Alternatives Considered
• Trade-offs / Drawbacks
• Open Questions
• Implementation Plan
1. What is being proposed? "replacing per-service Redis instances with a shared Redis Cluster"
2. Why? "reduce cost by ~$4,200/month and eliminate 3 on-call failure modes"
3. What is the constraint/success criterion? "while maintaining <5ms p99 cache latency"
This matters because senior engineers and stakeholders will read the title + first paragraph and decide whether to read further. If your opening is vague, persuasive, or personal-opinion-heavy, you lose credibility immediately.
RFC opening anti-patterns:
• "The author believes…" — RFCs make proposals, not personal arguments
• "As you all know…" — assumes shared context, signals lazy writing
• "Please read and let me know" — RFCs drive decisions, not open polls
• No numbers — quantify the problem whenever possible
Standard RFC sections:
• Abstract / Summary
• Motivation / Problem Statement
• Proposal / Design
• Alternatives Considered
• Trade-offs / Drawbacks
• Open Questions
• Implementation Plan
2 / 45
An RFC section is titled "Alternatives Considered." An engineer writes: "We considered using Memcached but rejected it." The section is weak. The most important improvement is to _____.
The "Alternatives Considered" section is often the most valuable part of an RFC — and the most commonly written poorly.
What weak alternatives sections look like:
"We considered X but decided against it." → completely useless
"We considered X but it didn't work." → vague and unconvincing
What strong alternatives sections look like:
"We considered Memcached as an alternative to Redis Cluster. Memcached would reduce operational complexity (simpler data model) but it lacks Redis's support for sorted sets and pub/sub, which our leaderboard and invalidation features require. Additionally, Memcached does not support persistence — a hard requirement from the DBA team."
Why this matters:
• It shows you thought deeply about the problem — not just the first solution you found
• It prevents readers from raising alternatives in review that you've already considered
• It documents the trade-off reasoning for future engineers who will ask "why didn't they just use X?"
• It builds trust: reviewers can see your reasoning, not just your conclusion
The number of alternatives is less important than the depth of reasoning for each one.
What weak alternatives sections look like:
"We considered X but decided against it." → completely useless
"We considered X but it didn't work." → vague and unconvincing
What strong alternatives sections look like:
"We considered Memcached as an alternative to Redis Cluster. Memcached would reduce operational complexity (simpler data model) but it lacks Redis's support for sorted sets and pub/sub, which our leaderboard and invalidation features require. Additionally, Memcached does not support persistence — a hard requirement from the DBA team."
Why this matters:
• It shows you thought deeply about the problem — not just the first solution you found
• It prevents readers from raising alternatives in review that you've already considered
• It documents the trade-off reasoning for future engineers who will ask "why didn't they just use X?"
• It builds trust: reviewers can see your reasoning, not just your conclusion
The number of alternatives is less important than the depth of reasoning for each one.
3 / 45
In an RFC's "Trade-offs" or "Drawbacks" section, an engineer writes: "This proposal has no significant drawbacks." A senior engineer says this is a red flag. Why?
"No significant drawbacks" is one of the most reliable signals that an RFC hasn't been thought through carefully enough.
Every engineering decision has trade-offs. Examples of real trade-offs to acknowledge:
• Increased complexity — "This adds a new service dependency"
• Operational overhead — "The team needs training on the new tool"
• Migration cost — "Migrating 40 services to the new API will take ~3 sprints"
• Performance in edge cases — "Under extreme load >10k RPS this approach adds 2ms latency"
• Vendor dependency — "We become dependent on Vendor X's support and pricing"
• Reversibility — "This migration is not easily reversible"
Why acknowledging drawbacks builds trust:
Readers know trade-offs exist. If you pretend they don't, readers assume you're either naive or selling something. Acknowledging limitations honestly demonstrates intellectual honesty and makes reviewers more likely to approve the proposal.
RFC vocabulary for drawbacks:
"The primary trade-off is…"
"One limitation of this approach is…"
"This introduces a potential risk of…"
"The migration cost is estimated at…"
"We accept this trade-off because…"
Every engineering decision has trade-offs. Examples of real trade-offs to acknowledge:
• Increased complexity — "This adds a new service dependency"
• Operational overhead — "The team needs training on the new tool"
• Migration cost — "Migrating 40 services to the new API will take ~3 sprints"
• Performance in edge cases — "Under extreme load >10k RPS this approach adds 2ms latency"
• Vendor dependency — "We become dependent on Vendor X's support and pricing"
• Reversibility — "This migration is not easily reversible"
Why acknowledging drawbacks builds trust:
Readers know trade-offs exist. If you pretend they don't, readers assume you're either naive or selling something. Acknowledging limitations honestly demonstrates intellectual honesty and makes reviewers more likely to approve the proposal.
RFC vocabulary for drawbacks:
"The primary trade-off is…"
"One limitation of this approach is…"
"This introduces a potential risk of…"
"The migration cost is estimated at…"
"We accept this trade-off because…"
4 / 45
An RFC includes a section titled "Open Questions." An engineer asks: "Why list things we don't know yet — doesn't that weaken the proposal?" What is the correct answer?
The "Open Questions" section is a deliberate and valuable tool in RFC writing, not a sign of weakness.
What Open Questions achieve:
• Surface decisions that are genuinely unknown or contested — instead of hiding them
• Invite reviewers with specific expertise to contribute ("I know the answer to Q3")
• Set expectations: "This RFC is approved in principle pending resolution of Q1 and Q2"
• Prevent the author from being the single bottleneck on all unknowns
Good open question examples:
"Should the cluster use 3 or 5 replica shards? We recommend 3 for cost, but the DBA team should validate."
"What SLA does the payments team require for cache misses? We need this to finalise the timeout configuration."
"Is the security team comfortable with shared Redis for PII-adjacent data? Requires sign-off."
Bad open question examples:
"How does Redis work?" (research question, not a decision)
"Should we do this?" (the RFC itself answers that)
RFC vocab for open questions:
"This remains an open question pending input from…"
"We have not yet determined whether…"
"This decision is deferred to…"
"Feedback needed: …"
What Open Questions achieve:
• Surface decisions that are genuinely unknown or contested — instead of hiding them
• Invite reviewers with specific expertise to contribute ("I know the answer to Q3")
• Set expectations: "This RFC is approved in principle pending resolution of Q1 and Q2"
• Prevent the author from being the single bottleneck on all unknowns
Good open question examples:
"Should the cluster use 3 or 5 replica shards? We recommend 3 for cost, but the DBA team should validate."
"What SLA does the payments team require for cache misses? We need this to finalise the timeout configuration."
"Is the security team comfortable with shared Redis for PII-adjacent data? Requires sign-off."
Bad open question examples:
"How does Redis work?" (research question, not a decision)
"Should we do this?" (the RFC itself answers that)
RFC vocab for open questions:
"This remains an open question pending input from…"
"We have not yet determined whether…"
"This decision is deferred to…"
"Feedback needed: …"
5 / 45
A tech lead reads an RFC and leaves this comment: "The proposal is technically sound but the RFC doesn't address the implementation plan." What is missing?
An RFC that lacks an implementation plan creates a common failure mode: it gets approved, then the team spends weeks figuring out how to actually execute it.
What a strong RFC implementation plan includes:
Phases: "Phase 1: Migrate 3 low-traffic services (Week 1-2). Phase 2: Migrate payments service (Week 3, requires Redis Cluster stable). Phase 3: Switch off old instances (Week 4)."
Owners: "Infrastructure migration: Platform team. Service-level changes: individual service owners."
Dependencies: "Phase 2 cannot start until Redis Cluster passes load testing."
Success metrics: "Cache hit rate ≥ 85%, p99 latency < 5ms, zero failed migrations."
Rollback plan: "If p99 latency exceeds 8ms, revert service-level connection strings to per-service Redis."
RFC implementation vocabulary:
"This will be rolled out in N phases, with phase 1 targeting…"
"Phase 2 is gated on [condition]."
"The rollback procedure is: …"
"Success will be measured by: …"
"Ownership: [team] is responsible for [scope]."
What a strong RFC implementation plan includes:
Phases: "Phase 1: Migrate 3 low-traffic services (Week 1-2). Phase 2: Migrate payments service (Week 3, requires Redis Cluster stable). Phase 3: Switch off old instances (Week 4)."
Owners: "Infrastructure migration: Platform team. Service-level changes: individual service owners."
Dependencies: "Phase 2 cannot start until Redis Cluster passes load testing."
Success metrics: "Cache hit rate ≥ 85%, p99 latency < 5ms, zero failed migrations."
Rollback plan: "If p99 latency exceeds 8ms, revert service-level connection strings to per-service Redis."
RFC implementation vocabulary:
"This will be rolled out in N phases, with phase 1 targeting…"
"Phase 2 is gated on [condition]."
"The rollback procedure is: …"
"Success will be measured by: …"
"Ownership: [team] is responsible for [scope]."
6 / 45
Sarah: "Hey team, I'm working on documenting the new API endpoint for user profile updates. The Slack message below is what I drafted to include in the PR description. What's the biggest issue with this?
'Just added a new endpoint to update user profiles! It handles name changes and email addresses. Happy coding!'The primary issue is the lack of clarity regarding required parameters. A good API documentation PR description needs to explicitly state which fields are mandatory for updates; otherwise, developers won't know how to correctly call the endpoint and could lead to errors or unexpected behavior. While the other options touch on aspects of good documentation (error handling, tone), defining required parameters is a core element for usability and reducing support requests.
Sarah's message prioritizes brevity over precise information, which is often detrimental in code reviews and API consumption.7 / 45
David: 'Hey team, I'm writing the PR description for this new feature. We're exposing a GraphQL endpoint that allows clients to fetch aggregated data based on various filters. The current draft says: 'New endpoint added – fetches data!' What's the most crucial addition to make this description more effective and aligned with RFC best practices?
Options:
The primary goal of an RFC and its associated PR description is to provide technical clarity. Option 1 addresses this directly by explaining the design choices – crucial for developers understanding how the endpoint functions and its limitations. Options 2, 3, and 4 are important but secondary; a developer needs to know *how* the data is structured and filtered before delving into performance or simply referencing the RFC. A good PR description should clearly communicate the technical details of the change.
8 / 45
Mark is reviewing a draft RFC for a new service. He finds the section on 'Future Enhancements' reads: 'This initial release will support basic authentication and data validation. Future enhancements may include multi-factor authentication and integration with third-party identity providers.' Mark comments, 'This feels a little vague. It doesn't give us much to go on for future development.' Which of the following responses is MOST appropriate for Mark to offer to the author?
The key here is understanding that an 'Future Enhancements' section in an RFC shouldn't be a speculative wishlist. It should outline *potential* directions for the service, but with enough clarity to inform architectural decisions and prioritization. Option 1 correctly identifies this by pointing out the lack of concrete details – it needs more than just stating possibilities; it requires discussing potential impacts and considerations. Options B, C, and D either misunderstand the purpose of that section or suggest a level of detail inappropriate for an early-stage RFC.
9 / 45
During a code review, Liam points out an RFC draft for a new payment processing system. He notes the 'Known Limitations' section states: 'The initial implementation will only support Visa and Mastercard transactions. Support for other card types will be added in a later release.' Another reviewer, Maya, suggests adding a sentence to the section about potential impacts on existing systems. Liam replies: 'Let's not over-engineer this now – it's just a small payment system.' What is the *primary* reason Maya's suggestion is valuable?
The correct answer highlights the importance of considering dependencies and impacts. While Liam's focus on a 'small payment system' is understandable, neglecting to document potential integration challenges in an RFC can lead to significant problems later. The 'Known Limitations' section should proactively address how this new system might interact with existing systems – this is crucial for risk mitigation and future development planning. Option A focuses on unnecessary detail; options B, C, and D misinterpret the purpose of the limitations section.
10 / 45
Alex is drafting an RFC for a new caching layer. He includes a section titled 'Performance Metrics.' Alex writes: 'Initial tests show a 20% reduction in API latency during peak load.' During a code review, his team lead asks, 'That's good, but what specific metrics are we tracking and how do they relate to our SLAs? How will we *prove* this improvement?' Which of the following is the MOST effective response Alex could offer to address his team lead's concerns?
The incorrect options demonstrate a lack of rigor and a failure to consider operational requirements. Option A dismisses important performance considerations. Option B focuses on internal benchmarks without connecting them to external SLAs. Option D suggests abandoning thorough investigation.
Option C highlights the crucial step of defining measurable metrics tied directly to Service Level Agreements, demonstrating a commitment to quantifiable improvement and providing evidence for ongoing monitoring – precisely what the team lead requested.11 / 45
Sarah: "Hey team, I'm working on documenting the new API endpoint for user profile updates. The Slack message below is what I drafted to include in the PR description. What's the biggest issue with this?
'Just added a new endpoint to update user profiles! It handles name changes and email addresses. Happy coding!'The primary issue is the lack of clarity regarding required parameters. A good API documentation PR description needs to explicitly state which fields are mandatory for updates; otherwise, developers won't know how to correctly call the endpoint and could lead to errors or unexpected behavior. While the other options touch on aspects of good documentation (error handling, tone), defining required parameters is a core element for usability and reducing support requests.
Sarah's message prioritizes brevity over precise information, which is often detrimental in code reviews and API consumption.12 / 45
David: 'Hey team, I'm writing the PR description for this new feature. We're exposing a GraphQL endpoint that allows clients to fetch aggregated data based on various filters. The current draft says: 'New endpoint added – fetches data!' What's the most crucial addition to make this description more effective and aligned with RFC best practices?
Options:
The primary goal of an RFC and its associated PR description is to provide technical clarity. Option 1 addresses this directly by explaining the design choices – crucial for developers understanding how the endpoint functions and its limitations. Options 2, 3, and 4 are important but secondary; a developer needs to know *how* the data is structured and filtered before delving into performance or simply referencing the RFC. A good PR description should clearly communicate the technical details of the change.
13 / 45
Mark is reviewing a draft RFC for a new service. He finds the section on 'Future Enhancements' reads: 'This initial release will support basic authentication and data validation. Future enhancements may include multi-factor authentication and integration with third-party identity providers.' Mark comments, 'This feels a little vague. It doesn't give us much to go on for future development.' Which of the following responses is MOST appropriate for Mark to offer to the author?
The key here is understanding that an 'Future Enhancements' section in an RFC shouldn't be a speculative wishlist. It should outline *potential* directions for the service, but with enough clarity to inform architectural decisions and prioritization. Option 1 correctly identifies this by pointing out the lack of concrete details – it needs more than just stating possibilities; it requires discussing potential impacts and considerations. Options B, C, and D either misunderstand the purpose of that section or suggest a level of detail inappropriate for an early-stage RFC.
14 / 45
During a code review, Liam points out an RFC draft for a new payment processing system. He notes the 'Known Limitations' section states: 'The initial implementation will only support Visa and Mastercard transactions. Support for other card types will be added in a later release.' Another reviewer, Maya, suggests adding a sentence to the section about potential impacts on existing systems. Liam replies: 'Let's not over-engineer this now – it's just a small payment system.' What is the *primary* reason Maya's suggestion is valuable?
The correct answer highlights the importance of considering dependencies and impacts. While Liam's focus on a 'small payment system' is understandable, neglecting to document potential integration challenges in an RFC can lead to significant problems later. The 'Known Limitations' section should proactively address how this new system might interact with existing systems – this is crucial for risk mitigation and future development planning. Option A focuses on unnecessary detail; options B, C, and D misinterpret the purpose of the limitations section.
15 / 45
Alex is drafting an RFC for a new caching layer. He includes a section titled 'Performance Metrics.' Alex writes: 'Initial tests show a 20% reduction in API latency during peak load.' During a code review, his team lead asks, 'That's good, but what specific metrics are we tracking and how do they relate to our SLAs? How will we *prove* this improvement?' Which of the following is the MOST effective response Alex could offer to address his team lead's concerns?
The incorrect options demonstrate a lack of rigor and a failure to consider operational requirements. Option A dismisses important performance considerations. Option B focuses on internal benchmarks without connecting them to external SLAs. Option D suggests abandoning thorough investigation.
Option C highlights the crucial step of defining measurable metrics tied directly to Service Level Agreements, demonstrating a commitment to quantifiable improvement and providing evidence for ongoing monitoring – precisely what the team lead requested.16 / 45
Sarah: "Hey team, I'm working on documenting the new API endpoint for user profile updates. The Slack message below is what I drafted to include in the PR description. What's the biggest issue with this?
'Just added a new endpoint to update user profiles! It handles name changes and email addresses. Happy coding!'The primary issue is the lack of clarity regarding required parameters. A good API documentation PR description needs to explicitly state which fields are mandatory for updates; otherwise, developers won't know how to correctly call the endpoint and could lead to errors or unexpected behavior. While the other options touch on aspects of good documentation (error handling, tone), defining required parameters is a core element for usability and reducing support requests.
Sarah's message prioritizes brevity over precise information, which is often detrimental in code reviews and API consumption.17 / 45
David: 'Hey team, I'm writing the PR description for this new feature. We're exposing a GraphQL endpoint that allows clients to fetch aggregated data based on various filters. The current draft says: 'New endpoint added – fetches data!' What's the most crucial addition to make this description more effective and aligned with RFC best practices?
Options:
The primary goal of an RFC and its associated PR description is to provide technical clarity. Option 1 addresses this directly by explaining the design choices – crucial for developers understanding how the endpoint functions and its limitations. Options 2, 3, and 4 are important but secondary; a developer needs to know *how* the data is structured and filtered before delving into performance or simply referencing the RFC. A good PR description should clearly communicate the technical details of the change.
18 / 45
Mark is reviewing a draft RFC for a new service. He finds the section on 'Future Enhancements' reads: 'This initial release will support basic authentication and data validation. Future enhancements may include multi-factor authentication and integration with third-party identity providers.' Mark comments, 'This feels a little vague. It doesn't give us much to go on for future development.' Which of the following responses is MOST appropriate for Mark to offer to the author?
The key here is understanding that an 'Future Enhancements' section in an RFC shouldn't be a speculative wishlist. It should outline *potential* directions for the service, but with enough clarity to inform architectural decisions and prioritization. Option 1 correctly identifies this by pointing out the lack of concrete details – it needs more than just stating possibilities; it requires discussing potential impacts and considerations. Options B, C, and D either misunderstand the purpose of that section or suggest a level of detail inappropriate for an early-stage RFC.
19 / 45
During a code review, Liam points out an RFC draft for a new payment processing system. He notes the 'Known Limitations' section states: 'The initial implementation will only support Visa and Mastercard transactions. Support for other card types will be added in a later release.' Another reviewer, Maya, suggests adding a sentence to the section about potential impacts on existing systems. Liam replies: 'Let's not over-engineer this now – it's just a small payment system.' What is the *primary* reason Maya's suggestion is valuable?
The correct answer highlights the importance of considering dependencies and impacts. While Liam's focus on a 'small payment system' is understandable, neglecting to document potential integration challenges in an RFC can lead to significant problems later. The 'Known Limitations' section should proactively address how this new system might interact with existing systems – this is crucial for risk mitigation and future development planning. Option A focuses on unnecessary detail; options B, C, and D misinterpret the purpose of the limitations section.
20 / 45
Alex is drafting an RFC for a new caching layer. He includes a section titled 'Performance Metrics.' Alex writes: 'Initial tests show a 20% reduction in API latency during peak load.' During a code review, his team lead asks, 'That's good, but what specific metrics are we tracking and how do they relate to our SLAs? How will we *prove* this improvement?' Which of the following is the MOST effective response Alex could offer to address his team lead's concerns?
The incorrect options demonstrate a lack of rigor and a failure to consider operational requirements. Option A dismisses important performance considerations. Option B focuses on internal benchmarks without connecting them to external SLAs. Option D suggests abandoning thorough investigation.
Option C highlights the crucial step of defining measurable metrics tied directly to Service Level Agreements, demonstrating a commitment to quantifiable improvement and providing evidence for ongoing monitoring – precisely what the team lead requested.21 / 45
Sarah: "Hey team, I'm working on documenting the new API endpoint for user profile updates. The Slack message below is what I drafted to include in the PR description. What's the biggest issue with this?
'Just added a new endpoint to update user profiles! It handles name changes and email addresses. Happy coding!'The primary issue is the lack of clarity regarding required parameters. A good API documentation PR description needs to explicitly state which fields are mandatory for updates; otherwise, developers won't know how to correctly call the endpoint and could lead to errors or unexpected behavior. While the other options touch on aspects of good documentation (error handling, tone), defining required parameters is a core element for usability and reducing support requests.
Sarah's message prioritizes brevity over precise information, which is often detrimental in code reviews and API consumption.22 / 45
David: 'Hey team, I'm writing the PR description for this new feature. We're exposing a GraphQL endpoint that allows clients to fetch aggregated data based on various filters. The current draft says: 'New endpoint added – fetches data!' What's the most crucial addition to make this description more effective and aligned with RFC best practices?
Options:
The primary goal of an RFC and its associated PR description is to provide technical clarity. Option 1 addresses this directly by explaining the design choices – crucial for developers understanding how the endpoint functions and its limitations. Options 2, 3, and 4 are important but secondary; a developer needs to know *how* the data is structured and filtered before delving into performance or simply referencing the RFC. A good PR description should clearly communicate the technical details of the change.
23 / 45
Mark is reviewing a draft RFC for a new service. He finds the section on 'Future Enhancements' reads: 'This initial release will support basic authentication and data validation. Future enhancements may include multi-factor authentication and integration with third-party identity providers.' Mark comments, 'This feels a little vague. It doesn't give us much to go on for future development.' Which of the following responses is MOST appropriate for Mark to offer to the author?
The key here is understanding that an 'Future Enhancements' section in an RFC shouldn't be a speculative wishlist. It should outline *potential* directions for the service, but with enough clarity to inform architectural decisions and prioritization. Option 1 correctly identifies this by pointing out the lack of concrete details – it needs more than just stating possibilities; it requires discussing potential impacts and considerations. Options B, C, and D either misunderstand the purpose of that section or suggest a level of detail inappropriate for an early-stage RFC.
24 / 45
During a code review, Liam points out an RFC draft for a new payment processing system. He notes the 'Known Limitations' section states: 'The initial implementation will only support Visa and Mastercard transactions. Support for other card types will be added in a later release.' Another reviewer, Maya, suggests adding a sentence to the section about potential impacts on existing systems. Liam replies: 'Let's not over-engineer this now – it's just a small payment system.' What is the *primary* reason Maya's suggestion is valuable?
The correct answer highlights the importance of considering dependencies and impacts. While Liam's focus on a 'small payment system' is understandable, neglecting to document potential integration challenges in an RFC can lead to significant problems later. The 'Known Limitations' section should proactively address how this new system might interact with existing systems – this is crucial for risk mitigation and future development planning. Option A focuses on unnecessary detail; options B, C, and D misinterpret the purpose of the limitations section.
25 / 45
Alex is drafting an RFC for a new caching layer. He includes a section titled 'Performance Metrics.' Alex writes: 'Initial tests show a 20% reduction in API latency during peak load.' During a code review, his team lead asks, 'That's good, but what specific metrics are we tracking and how do they relate to our SLAs? How will we *prove* this improvement?' Which of the following is the MOST effective response Alex could offer to address his team lead's concerns?
The incorrect options demonstrate a lack of rigor and a failure to consider operational requirements. Option A dismisses important performance considerations. Option B focuses on internal benchmarks without connecting them to external SLAs. Option D suggests abandoning thorough investigation.
Option C highlights the crucial step of defining measurable metrics tied directly to Service Level Agreements, demonstrating a commitment to quantifiable improvement and providing evidence for ongoing monitoring – precisely what the team lead requested.26 / 45
Sarah: "Hey team, I'm working on documenting the new API endpoint for user profile updates. The Slack message below is what I drafted to include in the PR description. What's the biggest issue with this?
'Just added a new endpoint to update user profiles! It handles name changes and email addresses. Happy coding!'The primary issue is the lack of clarity regarding required parameters. A good API documentation PR description needs to explicitly state which fields are mandatory for updates; otherwise, developers won't know how to correctly call the endpoint and could lead to errors or unexpected behavior. While the other options touch on aspects of good documentation (error handling, tone), defining required parameters is a core element for usability and reducing support requests.
Sarah's message prioritizes brevity over precise information, which is often detrimental in code reviews and API consumption.27 / 45
David: 'Hey team, I'm writing the PR description for this new feature. We're exposing a GraphQL endpoint that allows clients to fetch aggregated data based on various filters. The current draft says: 'New endpoint added – fetches data!' What's the most crucial addition to make this description more effective and aligned with RFC best practices?
Options:
The primary goal of an RFC and its associated PR description is to provide technical clarity. Option 1 addresses this directly by explaining the design choices – crucial for developers understanding how the endpoint functions and its limitations. Options 2, 3, and 4 are important but secondary; a developer needs to know *how* the data is structured and filtered before delving into performance or simply referencing the RFC. A good PR description should clearly communicate the technical details of the change.
28 / 45
Mark is reviewing a draft RFC for a new service. He finds the section on 'Future Enhancements' reads: 'This initial release will support basic authentication and data validation. Future enhancements may include multi-factor authentication and integration with third-party identity providers.' Mark comments, 'This feels a little vague. It doesn't give us much to go on for future development.' Which of the following responses is MOST appropriate for Mark to offer to the author?
The key here is understanding that an 'Future Enhancements' section in an RFC shouldn't be a speculative wishlist. It should outline *potential* directions for the service, but with enough clarity to inform architectural decisions and prioritization. Option 1 correctly identifies this by pointing out the lack of concrete details – it needs more than just stating possibilities; it requires discussing potential impacts and considerations. Options B, C, and D either misunderstand the purpose of that section or suggest a level of detail inappropriate for an early-stage RFC.
29 / 45
During a code review, Liam points out an RFC draft for a new payment processing system. He notes the 'Known Limitations' section states: 'The initial implementation will only support Visa and Mastercard transactions. Support for other card types will be added in a later release.' Another reviewer, Maya, suggests adding a sentence to the section about potential impacts on existing systems. Liam replies: 'Let's not over-engineer this now – it's just a small payment system.' What is the *primary* reason Maya's suggestion is valuable?
The correct answer highlights the importance of considering dependencies and impacts. While Liam's focus on a 'small payment system' is understandable, neglecting to document potential integration challenges in an RFC can lead to significant problems later. The 'Known Limitations' section should proactively address how this new system might interact with existing systems – this is crucial for risk mitigation and future development planning. Option A focuses on unnecessary detail; options B, C, and D misinterpret the purpose of the limitations section.
30 / 45
Alex is drafting an RFC for a new caching layer. He includes a section titled 'Performance Metrics.' Alex writes: 'Initial tests show a 20% reduction in API latency during peak load.' During a code review, his team lead asks, 'That's good, but what specific metrics are we tracking and how do they relate to our SLAs? How will we *prove* this improvement?' Which of the following is the MOST effective response Alex could offer to address his team lead's concerns?
The incorrect options demonstrate a lack of rigor and a failure to consider operational requirements. Option A dismisses important performance considerations. Option B focuses on internal benchmarks without connecting them to external SLAs. Option D suggests abandoning thorough investigation.
Option C highlights the crucial step of defining measurable metrics tied directly to Service Level Agreements, demonstrating a commitment to quantifiable improvement and providing evidence for ongoing monitoring – precisely what the team lead requested.31 / 45
Sarah: "Hey team, I'm working on documenting the new API endpoint for user profile updates. The Slack message below is what I drafted to include in the PR description. What's the biggest issue with this?
'Just added a new endpoint to update user profiles! It handles name changes and email addresses. Happy coding!'The primary issue is the lack of clarity regarding required parameters. A good API documentation PR description needs to explicitly state which fields are mandatory for updates; otherwise, developers won't know how to correctly call the endpoint and could lead to errors or unexpected behavior. While the other options touch on aspects of good documentation (error handling, tone), defining required parameters is a core element for usability and reducing support requests.
Sarah's message prioritizes brevity over precise information, which is often detrimental in code reviews and API consumption.32 / 45
David: 'Hey team, I'm writing the PR description for this new feature. We're exposing a GraphQL endpoint that allows clients to fetch aggregated data based on various filters. The current draft says: 'New endpoint added – fetches data!' What's the most crucial addition to make this description more effective and aligned with RFC best practices?
Options:
The primary goal of an RFC and its associated PR description is to provide technical clarity. Option 1 addresses this directly by explaining the design choices – crucial for developers understanding how the endpoint functions and its limitations. Options 2, 3, and 4 are important but secondary; a developer needs to know *how* the data is structured and filtered before delving into performance or simply referencing the RFC. A good PR description should clearly communicate the technical details of the change.
33 / 45
Mark is reviewing a draft RFC for a new service. He finds the section on 'Future Enhancements' reads: 'This initial release will support basic authentication and data validation. Future enhancements may include multi-factor authentication and integration with third-party identity providers.' Mark comments, 'This feels a little vague. It doesn't give us much to go on for future development.' Which of the following responses is MOST appropriate for Mark to offer to the author?
The key here is understanding that an 'Future Enhancements' section in an RFC shouldn't be a speculative wishlist. It should outline *potential* directions for the service, but with enough clarity to inform architectural decisions and prioritization. Option 1 correctly identifies this by pointing out the lack of concrete details – it needs more than just stating possibilities; it requires discussing potential impacts and considerations. Options B, C, and D either misunderstand the purpose of that section or suggest a level of detail inappropriate for an early-stage RFC.
34 / 45
During a code review, Liam points out an RFC draft for a new payment processing system. He notes the 'Known Limitations' section states: 'The initial implementation will only support Visa and Mastercard transactions. Support for other card types will be added in a later release.' Another reviewer, Maya, suggests adding a sentence to the section about potential impacts on existing systems. Liam replies: 'Let's not over-engineer this now – it's just a small payment system.' What is the *primary* reason Maya's suggestion is valuable?
The correct answer highlights the importance of considering dependencies and impacts. While Liam's focus on a 'small payment system' is understandable, neglecting to document potential integration challenges in an RFC can lead to significant problems later. The 'Known Limitations' section should proactively address how this new system might interact with existing systems – this is crucial for risk mitigation and future development planning. Option A focuses on unnecessary detail; options B, C, and D misinterpret the purpose of the limitations section.
35 / 45
Alex is drafting an RFC for a new caching layer. He includes a section titled 'Performance Metrics.' Alex writes: 'Initial tests show a 20% reduction in API latency during peak load.' During a code review, his team lead asks, 'That's good, but what specific metrics are we tracking and how do they relate to our SLAs? How will we *prove* this improvement?' Which of the following is the MOST effective response Alex could offer to address his team lead's concerns?
The incorrect options demonstrate a lack of rigor and a failure to consider operational requirements. Option A dismisses important performance considerations. Option B focuses on internal benchmarks without connecting them to external SLAs. Option D suggests abandoning thorough investigation.
Option C highlights the crucial step of defining measurable metrics tied directly to Service Level Agreements, demonstrating a commitment to quantifiable improvement and providing evidence for ongoing monitoring – precisely what the team lead requested.36 / 45
Sarah: "Hey team, I'm working on documenting the new API endpoint for user profile updates. The Slack message below is what I drafted to include in the PR description. What's the biggest issue with this?
'Just added a new endpoint to update user profiles! It handles name changes and email addresses. Happy coding!'The primary issue is the lack of clarity regarding required parameters. A good API documentation PR description needs to explicitly state which fields are mandatory for updates; otherwise, developers won't know how to correctly call the endpoint and could lead to errors or unexpected behavior. While the other options touch on aspects of good documentation (error handling, tone), defining required parameters is a core element for usability and reducing support requests.
Sarah's message prioritizes brevity over precise information, which is often detrimental in code reviews and API consumption.37 / 45
David: 'Hey team, I'm writing the PR description for this new feature. We're exposing a GraphQL endpoint that allows clients to fetch aggregated data based on various filters. The current draft says: 'New endpoint added – fetches data!' What's the most crucial addition to make this description more effective and aligned with RFC best practices?
Options:
The primary goal of an RFC and its associated PR description is to provide technical clarity. Option 1 addresses this directly by explaining the design choices – crucial for developers understanding how the endpoint functions and its limitations. Options 2, 3, and 4 are important but secondary; a developer needs to know *how* the data is structured and filtered before delving into performance or simply referencing the RFC. A good PR description should clearly communicate the technical details of the change.
38 / 45
Mark is reviewing a draft RFC for a new service. He finds the section on 'Future Enhancements' reads: 'This initial release will support basic authentication and data validation. Future enhancements may include multi-factor authentication and integration with third-party identity providers.' Mark comments, 'This feels a little vague. It doesn't give us much to go on for future development.' Which of the following responses is MOST appropriate for Mark to offer to the author?
The key here is understanding that an 'Future Enhancements' section in an RFC shouldn't be a speculative wishlist. It should outline *potential* directions for the service, but with enough clarity to inform architectural decisions and prioritization. Option 1 correctly identifies this by pointing out the lack of concrete details – it needs more than just stating possibilities; it requires discussing potential impacts and considerations. Options B, C, and D either misunderstand the purpose of that section or suggest a level of detail inappropriate for an early-stage RFC.
39 / 45
During a code review, Liam points out an RFC draft for a new payment processing system. He notes the 'Known Limitations' section states: 'The initial implementation will only support Visa and Mastercard transactions. Support for other card types will be added in a later release.' Another reviewer, Maya, suggests adding a sentence to the section about potential impacts on existing systems. Liam replies: 'Let's not over-engineer this now – it's just a small payment system.' What is the *primary* reason Maya's suggestion is valuable?
The correct answer highlights the importance of considering dependencies and impacts. While Liam's focus on a 'small payment system' is understandable, neglecting to document potential integration challenges in an RFC can lead to significant problems later. The 'Known Limitations' section should proactively address how this new system might interact with existing systems – this is crucial for risk mitigation and future development planning. Option A focuses on unnecessary detail; options B, C, and D misinterpret the purpose of the limitations section.
40 / 45
Alex is drafting an RFC for a new caching layer. He includes a section titled 'Performance Metrics.' Alex writes: 'Initial tests show a 20% reduction in API latency during peak load.' During a code review, his team lead asks, 'That's good, but what specific metrics are we tracking and how do they relate to our SLAs? How will we *prove* this improvement?' Which of the following is the MOST effective response Alex could offer to address his team lead's concerns?
The incorrect options demonstrate a lack of rigor and a failure to consider operational requirements. Option A dismisses important performance considerations. Option B focuses on internal benchmarks without connecting them to external SLAs. Option D suggests abandoning thorough investigation.
Option C highlights the crucial step of defining measurable metrics tied directly to Service Level Agreements, demonstrating a commitment to quantifiable improvement and providing evidence for ongoing monitoring – precisely what the team lead requested.41 / 45
Sarah: "Hey team, I'm working on documenting the new API endpoint for user profile updates. The Slack message below is what I drafted to include in the PR description. What's the biggest issue with this?
'Just added a new endpoint to update user profiles! It handles name changes and email addresses. Happy coding!'The primary issue is the lack of clarity regarding required parameters. A good API documentation PR description needs to explicitly state which fields are mandatory for updates; otherwise, developers won't know how to correctly call the endpoint and could lead to errors or unexpected behavior. While the other options touch on aspects of good documentation (error handling, tone), defining required parameters is a core element for usability and reducing support requests.
Sarah's message prioritizes brevity over precise information, which is often detrimental in code reviews and API consumption.42 / 45
David: 'Hey team, I'm writing the PR description for this new feature. We're exposing a GraphQL endpoint that allows clients to fetch aggregated data based on various filters. The current draft says: 'New endpoint added – fetches data!' What's the most crucial addition to make this description more effective and aligned with RFC best practices?
Options:
The primary goal of an RFC and its associated PR description is to provide technical clarity. Option 1 addresses this directly by explaining the design choices – crucial for developers understanding how the endpoint functions and its limitations. Options 2, 3, and 4 are important but secondary; a developer needs to know *how* the data is structured and filtered before delving into performance or simply referencing the RFC. A good PR description should clearly communicate the technical details of the change.
43 / 45
Mark is reviewing a draft RFC for a new service. He finds the section on 'Future Enhancements' reads: 'This initial release will support basic authentication and data validation. Future enhancements may include multi-factor authentication and integration with third-party identity providers.' Mark comments, 'This feels a little vague. It doesn't give us much to go on for future development.' Which of the following responses is MOST appropriate for Mark to offer to the author?
The key here is understanding that an 'Future Enhancements' section in an RFC shouldn't be a speculative wishlist. It should outline *potential* directions for the service, but with enough clarity to inform architectural decisions and prioritization. Option 1 correctly identifies this by pointing out the lack of concrete details – it needs more than just stating possibilities; it requires discussing potential impacts and considerations. Options B, C, and D either misunderstand the purpose of that section or suggest a level of detail inappropriate for an early-stage RFC.
44 / 45
During a code review, Liam points out an RFC draft for a new payment processing system. He notes the 'Known Limitations' section states: 'The initial implementation will only support Visa and Mastercard transactions. Support for other card types will be added in a later release.' Another reviewer, Maya, suggests adding a sentence to the section about potential impacts on existing systems. Liam replies: 'Let's not over-engineer this now – it's just a small payment system.' What is the *primary* reason Maya's suggestion is valuable?
The correct answer highlights the importance of considering dependencies and impacts. While Liam's focus on a 'small payment system' is understandable, neglecting to document potential integration challenges in an RFC can lead to significant problems later. The 'Known Limitations' section should proactively address how this new system might interact with existing systems – this is crucial for risk mitigation and future development planning. Option A focuses on unnecessary detail; options B, C, and D misinterpret the purpose of the limitations section.
45 / 45
Alex is drafting an RFC for a new caching layer. He includes a section titled 'Performance Metrics.' Alex writes: 'Initial tests show a 20% reduction in API latency during peak load.' During a code review, his team lead asks, 'That's good, but what specific metrics are we tracking and how do they relate to our SLAs? How will we *prove* this improvement?' Which of the following is the MOST effective response Alex could offer to address his team lead's concerns?
The incorrect options demonstrate a lack of rigor and a failure to consider operational requirements. Option A dismisses important performance considerations. Option B focuses on internal benchmarks without connecting them to external SLAs. Option D suggests abandoning thorough investigation.
Option C highlights the crucial step of defining measurable metrics tied directly to Service Level Agreements, demonstrating a commitment to quantifiable improvement and providing evidence for ongoing monitoring – precisely what the team lead requested.Frequently Asked Questions
What does the "RFC & Design Documents — Documentation Types Exercises" exercise cover?
Practice writing effective RFCs and technical design documents: openings, alternatives considered, trade-offs, open questions, and implementation plans. 5 exercises.
Is this exercise free to use?
Yes. Every exercise on CoderSlingo, including this one, is free to use with no account, sign-up, or paywall.
How many questions are in "RFC & Design Documents — Documentation Types Exercises"?
This exercise has 45 questions. Each one gives instant feedback with an explanation, so you can see exactly why an answer is right or wrong.
Do I need to create an account to save my progress?
No account is required. The progress bar and score are tracked in your browser for the current session -- the exercise is designed to be a quick, repeatable drill rather than something you resume later.
What happens if I get an answer wrong?
You'll see the correct answer highlighted immediately, along with a short explanation of why it's correct. Wrong answers aren't penalized beyond your score, and you can keep going through every question.
How is this exercise different from reading an article?
Articles explain vocabulary and concepts through prose, while exercises like this one are interactive drills -- multiple-choice questions -- that test and reinforce your recall of specific terms and phrasing.
Can I retry this exercise?
Yes -- use the "Try again" button on the results screen to reset your score and go through all the questions again from the start.
Where can I find more Documentation Types exercises?
Browse the full Documentation Types hub for related drills, or check the site-wide exercises index for other IT English topics.
Is this exercise suitable for beginners?
This exercise assumes basic familiarity with IT terminology. If a term feels unfamiliar, check the site Glossary for a plain-English definition before attempting the questions.
How often is new content like this published?
New exercises are added regularly across all categories, alongside new vocabulary sets and articles. Check back on the exercises hub to see what's new.