Intermediate
Documentation Types
#one-pager
#leadership
One-Pager Writing
4 exercises — write a one-pager / tech brief for leadership that is clear, concise, and persuasive within a 2-minute read.
0 / 44 completed
1 / 44
You are writing a one-pager to pitch a new engineering initiative to leadership, who will spend under 2 minutes reading it. Which opening line is correct?
A one-pager's opening line must deliver the ask, cost, and payoff in a single sentence — the "bottom line up front" (BLUF) principle. A busy executive should understand the entire proposal even if they read nothing else.
Formula:
Never open with throat-clearing ("this document discusses...") or vague background — a one-pager has no room for a slow build-up; every sentence must earn its place.
Formula:
"We propose [investment/ask] to [action], [quantified benefit] — [business impact]."Never open with throat-clearing ("this document discusses...") or vague background — a one-pager has no room for a slow build-up; every sentence must earn its place.
2 / 44
Which structure correctly organises the body of a persuasive one-pager after the opening line?
A one-pager should use short, labelled sections that a reader can scan in seconds — Problem, Proposal, Cost, Impact, Ask — each just a sentence or two. This is fundamentally different from a design doc or spec: the one-pager is a persuasion artifact for a non-implementing audience, not an implementation reference.
Structure: "Problem: [quantified pain]. Proposal: [what we'll do]. Cost: [investment]. Impact: [expected result]. Ask: [specific decision requested — approval, budget, headcount]."
Structure: "Problem: [quantified pain]. Proposal: [what we'll do]. Cost: [investment]. Impact: [expected result]. Ask: [specific decision requested — approval, budget, headcount]."
3 / 44
The final section of a one-pager should be a clear "Ask." Which is correctly written?
A one-pager exists to drive a decision, so the Ask must be specific and time-bound — exactly what is being requested (resources, approval, budget) and by when. Vague asks ("let us know what you think") produce no action and waste the document's purpose.
Formula:
If the one-pager truly is FYI-only with no ask, say so explicitly ("No action needed — for awareness only") rather than leaving the reader unsure what's expected of them.
Formula:
"Ask: [specific decision/resource requested]. [Deadline or urgency, if applicable]."If the one-pager truly is FYI-only with no ask, say so explicitly ("No action needed — for awareness only") rather than leaving the reader unsure what's expected of them.
4 / 44
A reviewer says your one-pager is "too technical for this audience." Which revision correctly addresses the feedback?
Adapting a one-pager for a non-technical audience means translating mechanism (JWT rotation, TTL) into outcome (what it means for security/risk) while keeping the concrete numbers that make the value tangible. This is not the same as removing all specificity — a good non-technical one-pager is still precise, just in outcome language rather than implementation language.
Technique: for each technical term, ask "what does this mean for the reader's goals (cost, risk, speed, revenue)?" and lead with that translation; technical detail can move to a linked appendix, not the one-pager itself.
Technique: for each technical term, ask "what does this mean for the reader's goals (cost, risk, speed, revenue)?" and lead with that translation; technical detail can move to a linked appendix, not the one-pager itself.
5 / 44
Sarah: "Hey team, I'm working on a new microservice to handle user profile updates. It uses Kafka for asynchronous processing and integrates with our existing database via gRPC. I've created a detailed API response schema and documented the gRPC calls in Swagger. (Attached: A draft PR description for this change)
This scenario reflects a common situation during code reviews. The goal of a PR description is to quickly inform reviewers about the *purpose* and *impact* of the change, not to provide exhaustive technical documentation. Including overly detailed information can overwhelm reviewers and slow down the process; instead, focus on the value proposition and how it relates to the broader system. Remember: One-pagers are meant for concise communication, prioritizing key elements over granular details.
6 / 44
John: "Hey team, I've drafted a one-pager outlining the proposed migration to PostgreSQL for our analytics database. It includes estimated downtime, potential rollback strategies, and performance benchmarks based on similar migrations we've done in the past. I think it clearly communicates the benefits and risks."This question assesses understanding of a key goal for documentation: objectivity. While John's enthusiasm is understandable, a one-pager intended for stakeholders needs to present information in a factual and measurable way. The 'correct' option acknowledges the document's purpose—clearly communicating benefits and risks—rather than relying on subjective assessment. Options B, C, and D all highlight areas where the statement lacks the necessary focus for effective communication.
7 / 44
David: "Hey team, I'm submitting a PR for the new authentication service. It's heavily reliant on JWTs and uses Redis for caching. The API documentation is in OpenAPI format, and I've included some example usage scenarios within the PR description itself. I wanted to keep it concise – around 3-4 paragraphs max."The core principle of a good one-pager (and PR description) is clarity and conciseness. David's approach—keeping it to 3-4 paragraphs—is appropriate for a quick review. While example scenarios are helpful, embedding them directly in the PR description can make it overly dense and harder to scan quickly. The key is to prioritize a clear summary of changes and their impact, which this response achieves.
8 / 44
Reviewer: 'This one-pager is great! However, I noticed you've focused heavily on the technical details of the new logging service – the specifics of the log format and the implementation of the agent. For this audience (product managers and marketing), they need to understand *why* we're doing this and what the key benefits are. Can you revise it to highlight the business impact more prominently?'This question tests your understanding of tailoring documentation to different audiences. The reviewer's feedback indicates a common mistake: prioritizing technical specifics over the broader business justification. A one-pager aimed at stakeholders needs to clearly articulate the 'why' – what problem are we solving, and what value are we delivering? Option 2 incorrectly prioritizes the technical details; instead, focus on highlighting the benefits for the intended audience.
9 / 44
Reviewer: 'I've reviewed the one-pager for the new payment gateway integration. While technically sound, it's primarily a list of technical specifications – API endpoints, data formats, and security protocols. This needs to be more compelling for stakeholders who aren't deeply involved in development. Consider adding a brief overview of the expected impact on key business metrics like revenue growth or customer satisfaction.' Which approach best addresses this feedback?
The core of the feedback is that the one-pager isn't compelling for non-technical stakeholders. Simply acknowledging the review doesn't solve this; it confirms the misunderstanding. Adding a section summarizing business outcomes—revenue growth, customer satisfaction—directly addresses the reviewer's concern by providing context and demonstrating value, which is what they need to understand the importance of the integration.
10 / 44
Sarah: "Hey team, I'm working on a new microservice to handle user profile updates. It uses Kafka for asynchronous processing and integrates with our existing database via gRPC. I've created a detailed API response schema and documented the gRPC calls in Swagger. (Attached: A draft PR description for this change)
This scenario reflects a common situation during code reviews. The goal of a PR description is to quickly inform reviewers about the *purpose* and *impact* of the change, not to provide exhaustive technical documentation. Including overly detailed information can overwhelm reviewers and slow down the process; instead, focus on the value proposition and how it relates to the broader system. Remember: One-pagers are meant for concise communication, prioritizing key elements over granular details.
11 / 44
John: "Hey team, I've drafted a one-pager outlining the proposed migration to PostgreSQL for our analytics database. It includes estimated downtime, potential rollback strategies, and performance benchmarks based on similar migrations we've done in the past. I think it clearly communicates the benefits and risks."This question assesses understanding of a key goal for documentation: objectivity. While John's enthusiasm is understandable, a one-pager intended for stakeholders needs to present information in a factual and measurable way. The 'correct' option acknowledges the document's purpose—clearly communicating benefits and risks—rather than relying on subjective assessment. Options B, C, and D all highlight areas where the statement lacks the necessary focus for effective communication.
12 / 44
David: "Hey team, I'm submitting a PR for the new authentication service. It's heavily reliant on JWTs and uses Redis for caching. The API documentation is in OpenAPI format, and I've included some example usage scenarios within the PR description itself. I wanted to keep it concise – around 3-4 paragraphs max."The core principle of a good one-pager (and PR description) is clarity and conciseness. David's approach—keeping it to 3-4 paragraphs—is appropriate for a quick review. While example scenarios are helpful, embedding them directly in the PR description can make it overly dense and harder to scan quickly. The key is to prioritize a clear summary of changes and their impact, which this response achieves.
13 / 44
Reviewer: 'This one-pager is great! However, I noticed you've focused heavily on the technical details of the new logging service – the specifics of the log format and the implementation of the agent. For this audience (product managers and marketing), they need to understand *why* we're doing this and what the key benefits are. Can you revise it to highlight the business impact more prominently?'This question tests your understanding of tailoring documentation to different audiences. The reviewer's feedback indicates a common mistake: prioritizing technical specifics over the broader business justification. A one-pager aimed at stakeholders needs to clearly articulate the 'why' – what problem are we solving, and what value are we delivering? Option 2 incorrectly prioritizes the technical details; instead, focus on highlighting the benefits for the intended audience.
14 / 44
Reviewer: 'I've reviewed the one-pager for the new payment gateway integration. While technically sound, it's primarily a list of technical specifications – API endpoints, data formats, and security protocols. This needs to be more compelling for stakeholders who aren't deeply involved in development. Consider adding a brief overview of the expected impact on key business metrics like revenue growth or customer satisfaction.' Which approach best addresses this feedback?
The core of the feedback is that the one-pager isn't compelling for non-technical stakeholders. Simply acknowledging the review doesn't solve this; it confirms the misunderstanding. Adding a section summarizing business outcomes—revenue growth, customer satisfaction—directly addresses the reviewer's concern by providing context and demonstrating value, which is what they need to understand the importance of the integration.
15 / 44
Sarah: "Hey team, I'm working on a new microservice to handle user profile updates. It uses Kafka for asynchronous processing and integrates with our existing database via gRPC. I've created a detailed API response schema and documented the gRPC calls in Swagger. (Attached: A draft PR description for this change)
This scenario reflects a common situation during code reviews. The goal of a PR description is to quickly inform reviewers about the *purpose* and *impact* of the change, not to provide exhaustive technical documentation. Including overly detailed information can overwhelm reviewers and slow down the process; instead, focus on the value proposition and how it relates to the broader system. Remember: One-pagers are meant for concise communication, prioritizing key elements over granular details.
16 / 44
John: "Hey team, I've drafted a one-pager outlining the proposed migration to PostgreSQL for our analytics database. It includes estimated downtime, potential rollback strategies, and performance benchmarks based on similar migrations we've done in the past. I think it clearly communicates the benefits and risks."This question assesses understanding of a key goal for documentation: objectivity. While John's enthusiasm is understandable, a one-pager intended for stakeholders needs to present information in a factual and measurable way. The 'correct' option acknowledges the document's purpose—clearly communicating benefits and risks—rather than relying on subjective assessment. Options B, C, and D all highlight areas where the statement lacks the necessary focus for effective communication.
17 / 44
David: "Hey team, I'm submitting a PR for the new authentication service. It's heavily reliant on JWTs and uses Redis for caching. The API documentation is in OpenAPI format, and I've included some example usage scenarios within the PR description itself. I wanted to keep it concise – around 3-4 paragraphs max."The core principle of a good one-pager (and PR description) is clarity and conciseness. David's approach—keeping it to 3-4 paragraphs—is appropriate for a quick review. While example scenarios are helpful, embedding them directly in the PR description can make it overly dense and harder to scan quickly. The key is to prioritize a clear summary of changes and their impact, which this response achieves.
18 / 44
Reviewer: 'This one-pager is great! However, I noticed you've focused heavily on the technical details of the new logging service – the specifics of the log format and the implementation of the agent. For this audience (product managers and marketing), they need to understand *why* we're doing this and what the key benefits are. Can you revise it to highlight the business impact more prominently?'This question tests your understanding of tailoring documentation to different audiences. The reviewer's feedback indicates a common mistake: prioritizing technical specifics over the broader business justification. A one-pager aimed at stakeholders needs to clearly articulate the 'why' – what problem are we solving, and what value are we delivering? Option 2 incorrectly prioritizes the technical details; instead, focus on highlighting the benefits for the intended audience.
19 / 44
Reviewer: 'I've reviewed the one-pager for the new payment gateway integration. While technically sound, it's primarily a list of technical specifications – API endpoints, data formats, and security protocols. This needs to be more compelling for stakeholders who aren't deeply involved in development. Consider adding a brief overview of the expected impact on key business metrics like revenue growth or customer satisfaction.' Which approach best addresses this feedback?
The core of the feedback is that the one-pager isn't compelling for non-technical stakeholders. Simply acknowledging the review doesn't solve this; it confirms the misunderstanding. Adding a section summarizing business outcomes—revenue growth, customer satisfaction—directly addresses the reviewer's concern by providing context and demonstrating value, which is what they need to understand the importance of the integration.
20 / 44
Sarah: "Hey team, I'm working on a new microservice to handle user profile updates. It uses Kafka for asynchronous processing and integrates with our existing database via gRPC. I've created a detailed API response schema and documented the gRPC calls in Swagger. (Attached: A draft PR description for this change)
This scenario reflects a common situation during code reviews. The goal of a PR description is to quickly inform reviewers about the *purpose* and *impact* of the change, not to provide exhaustive technical documentation. Including overly detailed information can overwhelm reviewers and slow down the process; instead, focus on the value proposition and how it relates to the broader system. Remember: One-pagers are meant for concise communication, prioritizing key elements over granular details.
21 / 44
John: "Hey team, I've drafted a one-pager outlining the proposed migration to PostgreSQL for our analytics database. It includes estimated downtime, potential rollback strategies, and performance benchmarks based on similar migrations we've done in the past. I think it clearly communicates the benefits and risks."This question assesses understanding of a key goal for documentation: objectivity. While John's enthusiasm is understandable, a one-pager intended for stakeholders needs to present information in a factual and measurable way. The 'correct' option acknowledges the document's purpose—clearly communicating benefits and risks—rather than relying on subjective assessment. Options B, C, and D all highlight areas where the statement lacks the necessary focus for effective communication.
22 / 44
David: "Hey team, I'm submitting a PR for the new authentication service. It's heavily reliant on JWTs and uses Redis for caching. The API documentation is in OpenAPI format, and I've included some example usage scenarios within the PR description itself. I wanted to keep it concise – around 3-4 paragraphs max."The core principle of a good one-pager (and PR description) is clarity and conciseness. David's approach—keeping it to 3-4 paragraphs—is appropriate for a quick review. While example scenarios are helpful, embedding them directly in the PR description can make it overly dense and harder to scan quickly. The key is to prioritize a clear summary of changes and their impact, which this response achieves.
23 / 44
Reviewer: 'This one-pager is great! However, I noticed you've focused heavily on the technical details of the new logging service – the specifics of the log format and the implementation of the agent. For this audience (product managers and marketing), they need to understand *why* we're doing this and what the key benefits are. Can you revise it to highlight the business impact more prominently?'This question tests your understanding of tailoring documentation to different audiences. The reviewer's feedback indicates a common mistake: prioritizing technical specifics over the broader business justification. A one-pager aimed at stakeholders needs to clearly articulate the 'why' – what problem are we solving, and what value are we delivering? Option 2 incorrectly prioritizes the technical details; instead, focus on highlighting the benefits for the intended audience.
24 / 44
Reviewer: 'I've reviewed the one-pager for the new payment gateway integration. While technically sound, it's primarily a list of technical specifications – API endpoints, data formats, and security protocols. This needs to be more compelling for stakeholders who aren't deeply involved in development. Consider adding a brief overview of the expected impact on key business metrics like revenue growth or customer satisfaction.' Which approach best addresses this feedback?
The core of the feedback is that the one-pager isn't compelling for non-technical stakeholders. Simply acknowledging the review doesn't solve this; it confirms the misunderstanding. Adding a section summarizing business outcomes—revenue growth, customer satisfaction—directly addresses the reviewer's concern by providing context and demonstrating value, which is what they need to understand the importance of the integration.
25 / 44
Sarah: "Hey team, I'm working on a new microservice to handle user profile updates. It uses Kafka for asynchronous processing and integrates with our existing database via gRPC. I've created a detailed API response schema and documented the gRPC calls in Swagger. (Attached: A draft PR description for this change)
This scenario reflects a common situation during code reviews. The goal of a PR description is to quickly inform reviewers about the *purpose* and *impact* of the change, not to provide exhaustive technical documentation. Including overly detailed information can overwhelm reviewers and slow down the process; instead, focus on the value proposition and how it relates to the broader system. Remember: One-pagers are meant for concise communication, prioritizing key elements over granular details.
26 / 44
John: "Hey team, I've drafted a one-pager outlining the proposed migration to PostgreSQL for our analytics database. It includes estimated downtime, potential rollback strategies, and performance benchmarks based on similar migrations we've done in the past. I think it clearly communicates the benefits and risks."This question assesses understanding of a key goal for documentation: objectivity. While John's enthusiasm is understandable, a one-pager intended for stakeholders needs to present information in a factual and measurable way. The 'correct' option acknowledges the document's purpose—clearly communicating benefits and risks—rather than relying on subjective assessment. Options B, C, and D all highlight areas where the statement lacks the necessary focus for effective communication.
27 / 44
David: "Hey team, I'm submitting a PR for the new authentication service. It's heavily reliant on JWTs and uses Redis for caching. The API documentation is in OpenAPI format, and I've included some example usage scenarios within the PR description itself. I wanted to keep it concise – around 3-4 paragraphs max."The core principle of a good one-pager (and PR description) is clarity and conciseness. David's approach—keeping it to 3-4 paragraphs—is appropriate for a quick review. While example scenarios are helpful, embedding them directly in the PR description can make it overly dense and harder to scan quickly. The key is to prioritize a clear summary of changes and their impact, which this response achieves.
28 / 44
Reviewer: 'This one-pager is great! However, I noticed you've focused heavily on the technical details of the new logging service – the specifics of the log format and the implementation of the agent. For this audience (product managers and marketing), they need to understand *why* we're doing this and what the key benefits are. Can you revise it to highlight the business impact more prominently?'This question tests your understanding of tailoring documentation to different audiences. The reviewer's feedback indicates a common mistake: prioritizing technical specifics over the broader business justification. A one-pager aimed at stakeholders needs to clearly articulate the 'why' – what problem are we solving, and what value are we delivering? Option 2 incorrectly prioritizes the technical details; instead, focus on highlighting the benefits for the intended audience.
29 / 44
Reviewer: 'I've reviewed the one-pager for the new payment gateway integration. While technically sound, it's primarily a list of technical specifications – API endpoints, data formats, and security protocols. This needs to be more compelling for stakeholders who aren't deeply involved in development. Consider adding a brief overview of the expected impact on key business metrics like revenue growth or customer satisfaction.' Which approach best addresses this feedback?
The core of the feedback is that the one-pager isn't compelling for non-technical stakeholders. Simply acknowledging the review doesn't solve this; it confirms the misunderstanding. Adding a section summarizing business outcomes—revenue growth, customer satisfaction—directly addresses the reviewer's concern by providing context and demonstrating value, which is what they need to understand the importance of the integration.
30 / 44
Sarah: "Hey team, I'm working on a new microservice to handle user profile updates. It uses Kafka for asynchronous processing and integrates with our existing database via gRPC. I've created a detailed API response schema and documented the gRPC calls in Swagger. (Attached: A draft PR description for this change)
This scenario reflects a common situation during code reviews. The goal of a PR description is to quickly inform reviewers about the *purpose* and *impact* of the change, not to provide exhaustive technical documentation. Including overly detailed information can overwhelm reviewers and slow down the process; instead, focus on the value proposition and how it relates to the broader system. Remember: One-pagers are meant for concise communication, prioritizing key elements over granular details.
31 / 44
John: "Hey team, I've drafted a one-pager outlining the proposed migration to PostgreSQL for our analytics database. It includes estimated downtime, potential rollback strategies, and performance benchmarks based on similar migrations we've done in the past. I think it clearly communicates the benefits and risks."This question assesses understanding of a key goal for documentation: objectivity. While John's enthusiasm is understandable, a one-pager intended for stakeholders needs to present information in a factual and measurable way. The 'correct' option acknowledges the document's purpose—clearly communicating benefits and risks—rather than relying on subjective assessment. Options B, C, and D all highlight areas where the statement lacks the necessary focus for effective communication.
32 / 44
David: "Hey team, I'm submitting a PR for the new authentication service. It's heavily reliant on JWTs and uses Redis for caching. The API documentation is in OpenAPI format, and I've included some example usage scenarios within the PR description itself. I wanted to keep it concise – around 3-4 paragraphs max."The core principle of a good one-pager (and PR description) is clarity and conciseness. David's approach—keeping it to 3-4 paragraphs—is appropriate for a quick review. While example scenarios are helpful, embedding them directly in the PR description can make it overly dense and harder to scan quickly. The key is to prioritize a clear summary of changes and their impact, which this response achieves.
33 / 44
Reviewer: 'This one-pager is great! However, I noticed you've focused heavily on the technical details of the new logging service – the specifics of the log format and the implementation of the agent. For this audience (product managers and marketing), they need to understand *why* we're doing this and what the key benefits are. Can you revise it to highlight the business impact more prominently?'This question tests your understanding of tailoring documentation to different audiences. The reviewer's feedback indicates a common mistake: prioritizing technical specifics over the broader business justification. A one-pager aimed at stakeholders needs to clearly articulate the 'why' – what problem are we solving, and what value are we delivering? Option 2 incorrectly prioritizes the technical details; instead, focus on highlighting the benefits for the intended audience.
34 / 44
Reviewer: 'I've reviewed the one-pager for the new payment gateway integration. While technically sound, it's primarily a list of technical specifications – API endpoints, data formats, and security protocols. This needs to be more compelling for stakeholders who aren't deeply involved in development. Consider adding a brief overview of the expected impact on key business metrics like revenue growth or customer satisfaction.' Which approach best addresses this feedback?
The core of the feedback is that the one-pager isn't compelling for non-technical stakeholders. Simply acknowledging the review doesn't solve this; it confirms the misunderstanding. Adding a section summarizing business outcomes—revenue growth, customer satisfaction—directly addresses the reviewer's concern by providing context and demonstrating value, which is what they need to understand the importance of the integration.
35 / 44
Sarah: "Hey team, I'm working on a new microservice to handle user profile updates. It uses Kafka for asynchronous processing and integrates with our existing database via gRPC. I've created a detailed API response schema and documented the gRPC calls in Swagger. (Attached: A draft PR description for this change)
This scenario reflects a common situation during code reviews. The goal of a PR description is to quickly inform reviewers about the *purpose* and *impact* of the change, not to provide exhaustive technical documentation. Including overly detailed information can overwhelm reviewers and slow down the process; instead, focus on the value proposition and how it relates to the broader system. Remember: One-pagers are meant for concise communication, prioritizing key elements over granular details.
36 / 44
John: "Hey team, I've drafted a one-pager outlining the proposed migration to PostgreSQL for our analytics database. It includes estimated downtime, potential rollback strategies, and performance benchmarks based on similar migrations we've done in the past. I think it clearly communicates the benefits and risks."This question assesses understanding of a key goal for documentation: objectivity. While John's enthusiasm is understandable, a one-pager intended for stakeholders needs to present information in a factual and measurable way. The 'correct' option acknowledges the document's purpose—clearly communicating benefits and risks—rather than relying on subjective assessment. Options B, C, and D all highlight areas where the statement lacks the necessary focus for effective communication.
37 / 44
David: "Hey team, I'm submitting a PR for the new authentication service. It's heavily reliant on JWTs and uses Redis for caching. The API documentation is in OpenAPI format, and I've included some example usage scenarios within the PR description itself. I wanted to keep it concise – around 3-4 paragraphs max."The core principle of a good one-pager (and PR description) is clarity and conciseness. David's approach—keeping it to 3-4 paragraphs—is appropriate for a quick review. While example scenarios are helpful, embedding them directly in the PR description can make it overly dense and harder to scan quickly. The key is to prioritize a clear summary of changes and their impact, which this response achieves.
38 / 44
Reviewer: 'This one-pager is great! However, I noticed you've focused heavily on the technical details of the new logging service – the specifics of the log format and the implementation of the agent. For this audience (product managers and marketing), they need to understand *why* we're doing this and what the key benefits are. Can you revise it to highlight the business impact more prominently?'This question tests your understanding of tailoring documentation to different audiences. The reviewer's feedback indicates a common mistake: prioritizing technical specifics over the broader business justification. A one-pager aimed at stakeholders needs to clearly articulate the 'why' – what problem are we solving, and what value are we delivering? Option 2 incorrectly prioritizes the technical details; instead, focus on highlighting the benefits for the intended audience.
39 / 44
Reviewer: 'I've reviewed the one-pager for the new payment gateway integration. While technically sound, it's primarily a list of technical specifications – API endpoints, data formats, and security protocols. This needs to be more compelling for stakeholders who aren't deeply involved in development. Consider adding a brief overview of the expected impact on key business metrics like revenue growth or customer satisfaction.' Which approach best addresses this feedback?
The core of the feedback is that the one-pager isn't compelling for non-technical stakeholders. Simply acknowledging the review doesn't solve this; it confirms the misunderstanding. Adding a section summarizing business outcomes—revenue growth, customer satisfaction—directly addresses the reviewer's concern by providing context and demonstrating value, which is what they need to understand the importance of the integration.
40 / 44
Sarah: "Hey team, I'm working on a new microservice to handle user profile updates. It uses Kafka for asynchronous processing and integrates with our existing database via gRPC. I've created a detailed API response schema and documented the gRPC calls in Swagger. (Attached: A draft PR description for this change)
This scenario reflects a common situation during code reviews. The goal of a PR description is to quickly inform reviewers about the *purpose* and *impact* of the change, not to provide exhaustive technical documentation. Including overly detailed information can overwhelm reviewers and slow down the process; instead, focus on the value proposition and how it relates to the broader system. Remember: One-pagers are meant for concise communication, prioritizing key elements over granular details.
41 / 44
John: "Hey team, I've drafted a one-pager outlining the proposed migration to PostgreSQL for our analytics database. It includes estimated downtime, potential rollback strategies, and performance benchmarks based on similar migrations we've done in the past. I think it clearly communicates the benefits and risks."This question assesses understanding of a key goal for documentation: objectivity. While John's enthusiasm is understandable, a one-pager intended for stakeholders needs to present information in a factual and measurable way. The 'correct' option acknowledges the document's purpose—clearly communicating benefits and risks—rather than relying on subjective assessment. Options B, C, and D all highlight areas where the statement lacks the necessary focus for effective communication.
42 / 44
David: "Hey team, I'm submitting a PR for the new authentication service. It's heavily reliant on JWTs and uses Redis for caching. The API documentation is in OpenAPI format, and I've included some example usage scenarios within the PR description itself. I wanted to keep it concise – around 3-4 paragraphs max."The core principle of a good one-pager (and PR description) is clarity and conciseness. David's approach—keeping it to 3-4 paragraphs—is appropriate for a quick review. While example scenarios are helpful, embedding them directly in the PR description can make it overly dense and harder to scan quickly. The key is to prioritize a clear summary of changes and their impact, which this response achieves.
43 / 44
Reviewer: 'This one-pager is great! However, I noticed you've focused heavily on the technical details of the new logging service – the specifics of the log format and the implementation of the agent. For this audience (product managers and marketing), they need to understand *why* we're doing this and what the key benefits are. Can you revise it to highlight the business impact more prominently?'This question tests your understanding of tailoring documentation to different audiences. The reviewer's feedback indicates a common mistake: prioritizing technical specifics over the broader business justification. A one-pager aimed at stakeholders needs to clearly articulate the 'why' – what problem are we solving, and what value are we delivering? Option 2 incorrectly prioritizes the technical details; instead, focus on highlighting the benefits for the intended audience.
44 / 44
Reviewer: 'I've reviewed the one-pager for the new payment gateway integration. While technically sound, it's primarily a list of technical specifications – API endpoints, data formats, and security protocols. This needs to be more compelling for stakeholders who aren't deeply involved in development. Consider adding a brief overview of the expected impact on key business metrics like revenue growth or customer satisfaction.' Which approach best addresses this feedback?
The core of the feedback is that the one-pager isn't compelling for non-technical stakeholders. Simply acknowledging the review doesn't solve this; it confirms the misunderstanding. Adding a section summarizing business outcomes—revenue growth, customer satisfaction—directly addresses the reviewer's concern by providing context and demonstrating value, which is what they need to understand the importance of the integration.
Frequently Asked Questions
What does the "One-Pager Writing — Documentation Types Exercise" exercise cover?
Practice writing persuasive one-pagers for leadership: bottom-line-up-front openings, scannable structure, clear asks, and non-technical framing. 4 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 "One-Pager Writing — Documentation Types Exercise"?
This exercise has 44 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.