Intermediate
Documentation Types
#design-doc
#architecture
Writing Design Documents (English)
8 exercises — practise the vocabulary and structure of technical design documents: goals, non-goals, alternatives considered, and design decisions.
0 / 29 completed
1 / 29
What is the purpose of a 'Goals' section in a design document?
The Goals section defines what success looks like for this design. It allows reviewers to evaluate whether the proposed solution actually achieves the stated objectives.
2 / 29
Why do design documents include a 'Non-Goals' section?
Non-goals define boundaries. Stating 'this design does not address multi-region support' prevents reviewers from expecting it and keeps discussions focused on what the design actually solves.
3 / 29
What should the 'Alternatives Considered' section of a design doc contain?
Alternatives Considered documents the trade-off analysis. It shows that the team explored the solution space and explains why the chosen approach is better for this context.
4 / 29
Which sentence is an example of good 'Design Decision' language in a design doc?
Good design decision language states the choice, the alternatives, the specific reason for the choice, and the context (query patterns, data volume). Vague or authority-based justifications are not useful for future readers.
5 / 29
What is 'open questions' section in a design document used for?
Open questions flag areas where the author is unsure, needs input, or where the team must make a decision before implementation begins. They invite focused review from the right people.
6 / 29
What distinguishes a design document from an RFC (Request for Comments)?
An RFC is a proposal explicitly seeking feedback from a defined audience (team, organization, or community). Design docs can also be collaborative but are often more focused on implementation details after key decisions are made.
7 / 29
How should you describe a security consideration in a design document?
Security considerations in a design doc should be specific: what is exposed, how it is protected, and what limitations exist. Deferring or delegating security without details is a red flag in design reviews.
8 / 29
What does 'operational considerations' cover in a design document?
Operational considerations address production readiness: how will you deploy it (feature flag? blue-green?), what metrics and alerts will you add, how will you roll back, and what goes in the runbook?
9 / 29
John posted this comment on a pull request: 'This implementation looks good, but I'm concerned about scalability. Can we add some metrics to track the number of requests per second and response times?'. Which part of a design document should
John's comment primarily be addressed in?
A. The 'Known Issues' section, outlining potential problems discovered during development. B. The 'Performance Considerations' subsection within the 'Operational Considerations' section, detailing how the system will behave under load. C. The 'Future Enhancements' section, where planned additions for later versions are documented. D. The 'API Response Schema' documentation, specifying the format of data returned by the API.
John's comment focuses on scalability and performance metrics – specifically tracking requests per second and response times. This directly relates to how the system will behave under load, which is precisely what the 'Performance Considerations' subsection within the broader 'Operational Considerations' section of a design document addresses. The other options are incorrect because they relate to different aspects of documentation: known issues are problems already identified, future enhancements are planned additions, and API response schemas describe data format, not operational performance.10 / 29
During a code review of a new microservice designed for user authentication, Sarah receives the following comment from David:
'This API endpoint returns a 403 Forbidden error when attempting to authenticate with invalid credentials. The documentation doesn't explicitly state this behavior, and it's unclear whether the service is intended to provide more detailed error messages.'
Which section of the design document should David's comment most directly prompt Sarah to update or expand upon?
Which section of the design document should David's comment most directly prompt Sarah to update or expand upon?
David's comment highlights a discrepancy between the documented API contract and its actual behavior – specifically, the lack of detail in error responses. This points directly to needing clarification within the 'API Contract' section, which should precisely define what an endpoint *returns*, not just what it *should* do. Options A, C, and D address broader concerns (error handling, security, user flow) but don't directly relate to the specific documentation gap David identified.
11 / 29
Mark is writing a design document for a new recommendation engine. He's drafting the 'Operational Considerations' section and needs to describe how the system will handle peak traffic. A colleague, Emily, asks: 'How do we ensure the system remains responsive during periods of high user activity?' Mark writes:
'The system will automatically scale up its compute resources based on demand.' Which aspect of the design document is Mark *most* directly addressing with this statement?
Mark is focusing on ensuring the system can handle increased demand – this falls squarely within scalability considerations. Option B correctly identifies that 'Scalability Considerations' is the appropriate place for detailing strategies like automatic scaling. The other options address related aspects (performance testing, monitoring, database schema) but don't directly tackle the core issue of how the system responds to peak traffic. This highlights the importance of organizing design documents by functional area.
12 / 29
You're reviewing the design document for a new payment processing service. The 'Risk Assessment' section identifies potential vulnerabilities related to fraudulent transactions. A junior developer, Liam, asks: 'Should we include a detailed breakdown of the mitigation strategies we plan to employ here?' Which part of the design document should you advise Liam to elaborate on?
The goal is to ensure the design document clearly communicates how risks are being addressed.
The question focuses on risk mitigation strategies. Option A (Security Requirements) is the most appropriate place to detail technical controls designed to address vulnerabilities like fraudulent transactions. Options B, C, and D relate to different aspects of the design document – performance, compliance, or disaster recovery – but don't directly address the proactive measures for dealing with identified risks. This highlights the importance of a structured approach to risk management within a design document.
13 / 29
John posted this comment on a pull request: 'This implementation looks good, but I'm concerned about scalability. Can we add some metrics to track the number of requests per second and response times?'. Which part of a design document should
John's comment primarily be addressed in?
A. The 'Known Issues' section, outlining potential problems discovered during development. B. The 'Performance Considerations' subsection within the 'Operational Considerations' section, detailing how the system will behave under load. C. The 'Future Enhancements' section, where planned additions for later versions are documented. D. The 'API Response Schema' documentation, specifying the format of data returned by the API.
John's comment focuses on scalability and performance metrics – specifically tracking requests per second and response times. This directly relates to how the system will behave under load, which is precisely what the 'Performance Considerations' subsection within the broader 'Operational Considerations' section of a design document addresses. The other options are incorrect because they relate to different aspects of documentation: known issues are problems already identified, future enhancements are planned additions, and API response schemas describe data format, not operational performance.14 / 29
During a code review of a new microservice designed for user authentication, Sarah receives the following comment from David:
'This API endpoint returns a 403 Forbidden error when attempting to authenticate with invalid credentials. The documentation doesn't explicitly state this behavior, and it's unclear whether the service is intended to provide more detailed error messages.'
Which section of the design document should David's comment most directly prompt Sarah to update or expand upon?
Which section of the design document should David's comment most directly prompt Sarah to update or expand upon?
David's comment highlights a discrepancy between the documented API contract and its actual behavior – specifically, the lack of detail in error responses. This points directly to needing clarification within the 'API Contract' section, which should precisely define what an endpoint *returns*, not just what it *should* do. Options A, C, and D address broader concerns (error handling, security, user flow) but don't directly relate to the specific documentation gap David identified.
15 / 29
Mark is writing a design document for a new recommendation engine. He's drafting the 'Operational Considerations' section and needs to describe how the system will handle peak traffic. A colleague, Emily, asks: 'How do we ensure the system remains responsive during periods of high user activity?' Mark writes:
'The system will automatically scale up its compute resources based on demand.' Which aspect of the design document is Mark *most* directly addressing with this statement?
Mark is focusing on ensuring the system can handle increased demand – this falls squarely within scalability considerations. Option B correctly identifies that 'Scalability Considerations' is the appropriate place for detailing strategies like automatic scaling. The other options address related aspects (performance testing, monitoring, database schema) but don't directly tackle the core issue of how the system responds to peak traffic. This highlights the importance of organizing design documents by functional area.
16 / 29
You're reviewing the design document for a new payment processing service. The 'Risk Assessment' section identifies potential vulnerabilities related to fraudulent transactions. A junior developer, Liam, asks: 'Should we include a detailed breakdown of the mitigation strategies we plan to employ here?' Which part of the design document should you advise Liam to elaborate on?
The goal is to ensure the design document clearly communicates how risks are being addressed.
The question focuses on risk mitigation strategies. Option A (Security Requirements) is the most appropriate place to detail technical controls designed to address vulnerabilities like fraudulent transactions. Options B, C, and D relate to different aspects of the design document – performance, compliance, or disaster recovery – but don't directly address the proactive measures for dealing with identified risks. This highlights the importance of a structured approach to risk management within a design document.
17 / 29
John posted this comment on a pull request: 'This implementation looks good, but I'm concerned about scalability. Can we add some metrics to track the number of requests per second and response times?'. Which part of a design document should
John's comment primarily be addressed in?
A. The 'Known Issues' section, outlining potential problems discovered during development. B. The 'Performance Considerations' subsection within the 'Operational Considerations' section, detailing how the system will behave under load. C. The 'Future Enhancements' section, where planned additions for later versions are documented. D. The 'API Response Schema' documentation, specifying the format of data returned by the API.
John's comment focuses on scalability and performance metrics – specifically tracking requests per second and response times. This directly relates to how the system will behave under load, which is precisely what the 'Performance Considerations' subsection within the broader 'Operational Considerations' section of a design document addresses. The other options are incorrect because they relate to different aspects of documentation: known issues are problems already identified, future enhancements are planned additions, and API response schemas describe data format, not operational performance.18 / 29
During a code review of a new microservice designed for user authentication, Sarah receives the following comment from David:
'This API endpoint returns a 403 Forbidden error when attempting to authenticate with invalid credentials. The documentation doesn't explicitly state this behavior, and it's unclear whether the service is intended to provide more detailed error messages.'
Which section of the design document should David's comment most directly prompt Sarah to update or expand upon?
Which section of the design document should David's comment most directly prompt Sarah to update or expand upon?
David's comment highlights a discrepancy between the documented API contract and its actual behavior – specifically, the lack of detail in error responses. This points directly to needing clarification within the 'API Contract' section, which should precisely define what an endpoint *returns*, not just what it *should* do. Options A, C, and D address broader concerns (error handling, security, user flow) but don't directly relate to the specific documentation gap David identified.
19 / 29
Mark is writing a design document for a new recommendation engine. He's drafting the 'Operational Considerations' section and needs to describe how the system will handle peak traffic. A colleague, Emily, asks: 'How do we ensure the system remains responsive during periods of high user activity?' Mark writes:
'The system will automatically scale up its compute resources based on demand.' Which aspect of the design document is Mark *most* directly addressing with this statement?
Mark is focusing on ensuring the system can handle increased demand – this falls squarely within scalability considerations. Option B correctly identifies that 'Scalability Considerations' is the appropriate place for detailing strategies like automatic scaling. The other options address related aspects (performance testing, monitoring, database schema) but don't directly tackle the core issue of how the system responds to peak traffic. This highlights the importance of organizing design documents by functional area.
20 / 29
You're reviewing the design document for a new payment processing service. The 'Risk Assessment' section identifies potential vulnerabilities related to fraudulent transactions. A junior developer, Liam, asks: 'Should we include a detailed breakdown of the mitigation strategies we plan to employ here?' Which part of the design document should you advise Liam to elaborate on?
The goal is to ensure the design document clearly communicates how risks are being addressed.
The question focuses on risk mitigation strategies. Option A (Security Requirements) is the most appropriate place to detail technical controls designed to address vulnerabilities like fraudulent transactions. Options B, C, and D relate to different aspects of the design document – performance, compliance, or disaster recovery – but don't directly address the proactive measures for dealing with identified risks. This highlights the importance of a structured approach to risk management within a design document.
21 / 29
John posted this comment on a pull request: 'This implementation looks good, but I'm concerned about scalability. Can we add some metrics to track the number of requests per second and response times?'. Which part of a design document should
John's comment primarily be addressed in?
A. The 'Known Issues' section, outlining potential problems discovered during development. B. The 'Performance Considerations' subsection within the 'Operational Considerations' section, detailing how the system will behave under load. C. The 'Future Enhancements' section, where planned additions for later versions are documented. D. The 'API Response Schema' documentation, specifying the format of data returned by the API.
John's comment focuses on scalability and performance metrics – specifically tracking requests per second and response times. This directly relates to how the system will behave under load, which is precisely what the 'Performance Considerations' subsection within the broader 'Operational Considerations' section of a design document addresses. The other options are incorrect because they relate to different aspects of documentation: known issues are problems already identified, future enhancements are planned additions, and API response schemas describe data format, not operational performance.22 / 29
During a code review of a new microservice designed for user authentication, Sarah receives the following comment from David:
'This API endpoint returns a 403 Forbidden error when attempting to authenticate with invalid credentials. The documentation doesn't explicitly state this behavior, and it's unclear whether the service is intended to provide more detailed error messages.'
Which section of the design document should David's comment most directly prompt Sarah to update or expand upon?
Which section of the design document should David's comment most directly prompt Sarah to update or expand upon?
David's comment highlights a discrepancy between the documented API contract and its actual behavior – specifically, the lack of detail in error responses. This points directly to needing clarification within the 'API Contract' section, which should precisely define what an endpoint *returns*, not just what it *should* do. Options A, C, and D address broader concerns (error handling, security, user flow) but don't directly relate to the specific documentation gap David identified.
23 / 29
Mark is writing a design document for a new recommendation engine. He's drafting the 'Operational Considerations' section and needs to describe how the system will handle peak traffic. A colleague, Emily, asks: 'How do we ensure the system remains responsive during periods of high user activity?' Mark writes:
'The system will automatically scale up its compute resources based on demand.' Which aspect of the design document is Mark *most* directly addressing with this statement?
Mark is focusing on ensuring the system can handle increased demand – this falls squarely within scalability considerations. Option B correctly identifies that 'Scalability Considerations' is the appropriate place for detailing strategies like automatic scaling. The other options address related aspects (performance testing, monitoring, database schema) but don't directly tackle the core issue of how the system responds to peak traffic. This highlights the importance of organizing design documents by functional area.
24 / 29
You're reviewing the design document for a new payment processing service. The 'Risk Assessment' section identifies potential vulnerabilities related to fraudulent transactions. A junior developer, Liam, asks: 'Should we include a detailed breakdown of the mitigation strategies we plan to employ here?' Which part of the design document should you advise Liam to elaborate on?
The goal is to ensure the design document clearly communicates how risks are being addressed.
The question focuses on risk mitigation strategies. Option A (Security Requirements) is the most appropriate place to detail technical controls designed to address vulnerabilities like fraudulent transactions. Options B, C, and D relate to different aspects of the design document – performance, compliance, or disaster recovery – but don't directly address the proactive measures for dealing with identified risks. This highlights the importance of a structured approach to risk management within a design document.
25 / 29
During a Slack discussion about the design of a new API gateway, Alex says: 'We need to document the expected response codes for each endpoint. Specifically, I want to ensure we cover scenarios where the service is temporarily unavailable and returns a 503 Service Unavailable error.' Which statement best describes the purpose of this communication within a design document?
This statement highlights the importance of proactively documenting error responses. A robust design document should anticipate potential failures and clearly outline how the system handles them – including appropriate response codes like 503. The goal is to reduce ambiguity and improve troubleshooting.
26 / 29
As a technical writer drafting a design document for a new distributed queue system, you're explaining the retry policy. A developer asks: 'What happens if a message consistently fails after multiple retries?' Which of the following is the MOST appropriate way to phrase this in the documentation?
A well-defined retry policy needs specific parameters. Clearly stating a maximum number of retries and detailing what happens after those attempts (e.g., dead-letter queue) provides actionable information for developers implementing the system. This avoids ambiguity and ensures consistent behavior.
27 / 29
You're reviewing a PR description for a new microservice that processes image uploads. The description reads: 'This service handles user uploaded images, storing them in S3 and generating thumbnails.' To improve this description, what would be the MOST valuable addition?
While the initial description is functional, it lacks critical security considerations. Authentication and authorization are paramount when dealing with user-uploaded content. Including this information ensures developers understand how access control is managed and prevents potential vulnerabilities.
28 / 29
During a standup meeting, Sarah explains the design document for a new recommendation engine: 'We're using collaborative filtering to generate recommendations. We'll be tracking user interactions – clicks, purchases, ratings – and feeding that data into a machine learning model.' Which aspect of this explanation is MOST important from a documentation perspective?
The core of any design document lies in understanding *how* it works. In this case, specifying the data sources and metrics used to train the machine learning model is crucial for reproducibility, monitoring, and future improvements. Knowing what data feeds the model dictates how its performance can be evaluated.
29 / 29
You're tasked with creating a section in a design document for a new feature that allows users to export their data. A senior developer asks: 'How do we ensure the exported data is consistent and accurate across different systems?' Which of the following approaches would be MOST appropriate to document?
Data consistency across systems requires rigorous validation. Documenting a data validation process, including checksums and version control of the exported data, demonstrates a commitment to accuracy and reliability. This approach provides a clear methodology for ensuring that the exported data matches the source data.
Frequently Asked Questions
What does the "Design Doc Writing — Documentation Types Exercise" exercise cover?
Practice writing technical design documents: goals, non-goals, alternatives considered, design decisions, security and operational considerations. 8 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 "Design Doc Writing — Documentation Types Exercise"?
This exercise has 29 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.