Intermediate
Developer Relations
#tutorials#technical-writing#devrel
Tutorial Writing
5 exercises — Practice structuring developer tutorials: writing prerequisites, atomic steps, troubleshooting sections, checkpoints, and learning-consolidating conclusions.
0 / 45 completed
1 / 45
A tutorial about building a REST API begins: "In this tutorial, you'll learn how to build a REST API using Node.js and Express. We assume you have some programming experience." What is missing from this introduction?
Tutorial introductions must answer three questions: Who is this for? What will they build? How long will it take?
The three required elements:
1. Specific prerequisites — not "some programming experience" but "Node.js v18+, npm, basic JavaScript knowledge (functions, async/await)"
2. Specific outcome — "By the end, you'll have a working REST API that accepts JSON POST requests and returns paginated data"
3. Time estimate — "Takes about 45 minutes"
These elements help readers self-qualify: "Is this too easy? Too hard? Too long for right now?"
Without them, readers either:
• Abandon midway when they hit unfamiliar tools
• Skip a tutorial that would have been perfect for them
Key vocabulary:
• Prerequisites — skills, tools, and environment required before starting
• Expected outcome — the specific thing the reader will have built by the end
• Time estimate — approximate completion time to help readers plan
• Reader self-qualification — helping readers decide if the tutorial is the right level for them
The three required elements:
1. Specific prerequisites — not "some programming experience" but "Node.js v18+, npm, basic JavaScript knowledge (functions, async/await)"
2. Specific outcome — "By the end, you'll have a working REST API that accepts JSON POST requests and returns paginated data"
3. Time estimate — "Takes about 45 minutes"
These elements help readers self-qualify: "Is this too easy? Too hard? Too long for right now?"
Without them, readers either:
• Abandon midway when they hit unfamiliar tools
• Skip a tutorial that would have been perfect for them
Key vocabulary:
• Prerequisites — skills, tools, and environment required before starting
• Expected outcome — the specific thing the reader will have built by the end
• Time estimate — approximate completion time to help readers plan
• Reader self-qualification — helping readers decide if the tutorial is the right level for them
2 / 45
A tutorial step says: "Now configure your database connection." What is wrong with this instruction?
Tutorial steps must be atomic, specific, and show both the action and the expected result.
The anatomy of a good tutorial step:
1. Imperative verb + specific action — "Add the following to your
2. Code block — with the specific code to type
3. Expected result — "When you run
4. Brief explanation (optional but valuable) — "DATABASE_URL tells Prisma which database to connect to"
"Now configure your database connection" fails all four — it describes a goal, not an action. The reader is left wondering:
• What file do I edit?
• What do I type?
• How do I know if it worked?
Key vocabulary:
• Atomic step — a step that describes exactly one action with a clear success state
• Imperative instruction — steps written in command form: "Open", "Add", "Run", "Create"
• Expected result — the output or state change the reader should see after completing a step
• Code block — a formatted section showing exact commands or code to type
The anatomy of a good tutorial step:
1. Imperative verb + specific action — "Add the following to your
.env file:"2. Code block — with the specific code to type
3. Expected result — "When you run
npm run db:connect, you should see: Database connected ✓"4. Brief explanation (optional but valuable) — "DATABASE_URL tells Prisma which database to connect to"
"Now configure your database connection" fails all four — it describes a goal, not an action. The reader is left wondering:
• What file do I edit?
• What do I type?
• How do I know if it worked?
Key vocabulary:
• Atomic step — a step that describes exactly one action with a clear success state
• Imperative instruction — steps written in command form: "Open", "Add", "Run", "Create"
• Expected result — the output or state change the reader should see after completing a step
• Code block — a formatted section showing exact commands or code to type
3 / 45
A reader runs a command in a tutorial and gets an error the tutorial doesn't address. What should an ideal tutorial include to handle this?
Tutorials must anticipate failure — the troubleshooting section is as important as the happy path.
Two types of error handling in tutorials:
1. Inline error handling — on steps most likely to fail:
"If you see 'ENOENT: no such file', check that you ran the previous step from the project root directory."
2. Troubleshooting section — at the end, listing the 3-5 most common errors:
"Error: connect ECONNREFUSED → Your PostgreSQL server isn't running. Run:
Why Option A fails: forum deflection is lazy; it means the author hasn't done the work.
Why Option B is impossible: different OS, permissions, versions, and environments mean errors are inevitable.
Why Option D fails: tutorials must work across macOS, Linux, and Windows — testing on one OS is insufficient.
Key vocabulary:
• Happy path — the successful path through a tutorial where nothing goes wrong
• Troubleshooting section — a section at the end of a tutorial covering common failure scenarios
• Inline error handling — step-specific notes about likely errors and their solutions
• OS-specific note — a callout for steps that differ between Windows, macOS, and Linux
Two types of error handling in tutorials:
1. Inline error handling — on steps most likely to fail:
"If you see 'ENOENT: no such file', check that you ran the previous step from the project root directory."
2. Troubleshooting section — at the end, listing the 3-5 most common errors:
"Error: connect ECONNREFUSED → Your PostgreSQL server isn't running. Run:
brew services start postgresql"Why Option A fails: forum deflection is lazy; it means the author hasn't done the work.
Why Option B is impossible: different OS, permissions, versions, and environments mean errors are inevitable.
Why Option D fails: tutorials must work across macOS, Linux, and Windows — testing on one OS is insufficient.
Key vocabulary:
• Happy path — the successful path through a tutorial where nothing goes wrong
• Troubleshooting section — a section at the end of a tutorial covering common failure scenarios
• Inline error handling — step-specific notes about likely errors and their solutions
• OS-specific note — a callout for steps that differ between Windows, macOS, and Linux
4 / 45
A tutorial has 24 steps with no breaks or intermediate checkpoints. A reader is on step 18 and realizes something went wrong several steps back. What tutorial structure would have prevented this?
Long tutorials need checkpoints — intermediate verification moments that let readers confirm they're on track before proceeding.
Checkpoint structure:
1. State description — "At this point, you should have: a running server at localhost:3000, a connected database, and 3 API endpoints"
2. Verification method — "Run:
3. Recovery instruction — "If your health check fails, check step 12 — the PORT environment variable may not be set"
Checkpoints work like git commits — they give readers a known-good state to return to if something goes wrong.
Checkpoint frequency guidelines:
• Every 5-7 significant steps
• After any complex configuration
• Before significant build milestones
Key vocabulary:
• Checkpoint — an intermediate verification step in a tutorial confirming correct state before continuing
• Verification command — a command that readers run to confirm their setup is correct
• Known-good state — a confirmed, working point in a tutorial from which the reader can continue confidently
• Recovery path — instructions for how to get back to a known-good state after an error
Checkpoint structure:
1. State description — "At this point, you should have: a running server at localhost:3000, a connected database, and 3 API endpoints"
2. Verification method — "Run:
curl localhost:3000/health. Expected output: {"status": "ok"}"3. Recovery instruction — "If your health check fails, check step 12 — the PORT environment variable may not be set"
Checkpoints work like git commits — they give readers a known-good state to return to if something goes wrong.
Checkpoint frequency guidelines:
• Every 5-7 significant steps
• After any complex configuration
• Before significant build milestones
Key vocabulary:
• Checkpoint — an intermediate verification step in a tutorial confirming correct state before continuing
• Verification command — a command that readers run to confirm their setup is correct
• Known-good state — a confirmed, working point in a tutorial from which the reader can continue confidently
• Recovery path — instructions for how to get back to a known-good state after an error
5 / 45
A tutorial ends with "You've completed the tutorial!" and nothing more. What should be added to the conclusion?
Tutorial conclusions must consolidate learning and immediately provide the next learning challenge.
The four elements of a strong tutorial conclusion:
1. What was built — one-sentence summary of the outcome
2. What was learned — the key concepts or patterns (2-3 bullet points)
3. Next steps — 2-3 specific, progressively harder challenges:
• Easy: "Add authentication to the API" (with link)
• Medium: "Deploy to Railway with CI/CD" (with link)
• Advanced: "Add a rate limiter and caching layer"
4. Completed code — a link to the final repository
Option B (20+ links) creates decision paralysis — too many options = no action taken.
Key vocabulary:
• Learning consolidation — restating the key lesson after completion to reinforce retention
• Progressive next steps — follow-up challenges ordered by increase in difficulty
• Decision paralysis — choice overload that causes readers to take no action (too many links)
• Completed code repository — the final, working code as a reference solution
The four elements of a strong tutorial conclusion:
1. What was built — one-sentence summary of the outcome
2. What was learned — the key concepts or patterns (2-3 bullet points)
3. Next steps — 2-3 specific, progressively harder challenges:
• Easy: "Add authentication to the API" (with link)
• Medium: "Deploy to Railway with CI/CD" (with link)
• Advanced: "Add a rate limiter and caching layer"
4. Completed code — a link to the final repository
Option B (20+ links) creates decision paralysis — too many options = no action taken.
Key vocabulary:
• Learning consolidation — restating the key lesson after completion to reinforce retention
• Progressive next steps — follow-up challenges ordered by increase in difficulty
• Decision paralysis — choice overload that causes readers to take no action (too many links)
• Completed code repository — the final, working code as a reference solution
6 / 45
David: "Hey team, I'm trying to implement this new feature based on the tutorial. It's supposed to automatically handle user authentication, but it keeps throwing a 401 Unauthorized error. The tutorial just says 'Configure your authentication middleware.' That's not helpful!" Which of the following is the BEST response David should give his teammate,
Sarah, who wrote the tutorial?David is frustrated because the tutorial offers no concrete advice for troubleshooting a common error. The core issue isn't necessarily that 'configure authentication middleware' is *wrong*, but rather that it doesn't offer guidance on *how* to do so or what specific errors might indicate. A good tutorial should anticipate potential issues and provide debugging steps, not just present instructions without context. This highlights the importance of including common error scenarios and their resolutions within developer documentation.
7 / 45
John: "Hey team, I'm writing a tutorial on deploying Docker containers to Kubernetes. The current draft says: 'Set up your kubectl configuration.' It's incredibly vague – what do they actually *mean*? Should I include detailed steps on installing `kubectl` and configuring the cluster context?"John's question highlights a common issue in tutorial writing: assuming the reader has a baseline level of knowledge. While it *is* appropriate to seek clarification, his phrasing indicates he's struggling with the basic requirements. The correct answer acknowledges this – a good developer relation exercise should teach that detailed instructions are often necessary when users encounter vagueness and need concrete guidance on *how* to achieve the stated goal. Over-engineering a tutorial by adding irrelevant steps is also a common mistake.8 / 45
Daniel: "Hey team, I'm following the tutorial for setting up our new CI/CD pipeline. It says, 'Trigger a build on every push to the main branch.' But I'm not sure how that actually works – does it automatically run tests and deploy? The tutorial doesn't explain what 'triggering a build' entails."This question assesses understanding of user expectations in a tutorial. While screenshots can be helpful, simply stating the command is insufficient without context. The core issue here is that users need to understand *what* 'triggering a build' actually *does*. A good explanation would break down the process and highlight what follows from initiating it – this prevents the reader from assuming they just run a command and everything happens automatically.
9 / 45
PR Description:
Subject: Fix: Resolve NullPointerException in UserProfileService when fetching profile by ID.
Details:
This PR addresses a critical NullPointerException that occurs within the `UserProfileService` during retrieval of user profiles based on their unique identifier. The issue was triggered when the database returned a null value for the userId field, which wasn't properly handled in the service logic leading to a crash.
The fix involves adding a null check before accessing the userId property, ensuring that the code gracefully handles this scenario and avoids the exception. Comprehensive unit tests have been implemented to verify the correctness of the solution.
@john.doe @jane.smithThis question assesses understanding of effective PR descriptions. The incorrect options either lack crucial details (option 1), provide overly technical explanations (option 2) or are excessively verbose (option 3). The correct answer highlights that a good description summarizes the problem, explains the fix, and includes relevant contact information – mirroring best practices for developer communication. A clear PR description helps reviewers quickly grasp the changes and their importance.
10 / 45
You're reviewing a tutorial for setting up a new microservice. The tutorial provides a section on deploying the service to AWS ECS. One of the steps reads: 'Configure your IAM role with appropriate permissions.' The tutorial doesn't explain what an IAM role is, nor does it provide any guidance on creating or configuring one. What's the MOST helpful comment you should leave on this step for the author?
Option A: 'This is great! It clearly outlines the necessary steps to deploy.'
Option B: 'Could you add a brief explanation of what an IAM role is and provide instructions on creating one with the required permissions for accessing AWS resources?'
Option C: 'The tutorial should include screenshots showing the exact configuration settings needed in the AWS console.'
Option D: 'This step assumes the user already has experience with AWS, which isn't always the case.'
Option A: 'This is great! It clearly outlines the necessary steps to deploy.'
Option B: 'Could you add a brief explanation of what an IAM role is and provide instructions on creating one with the required permissions for accessing AWS resources?'
Option C: 'The tutorial should include screenshots showing the exact configuration settings needed in the AWS console.'
Option D: 'This step assumes the user already has experience with AWS, which isn't always the case.'
The author's instruction is too vague and assumes a level of knowledge (IAM roles) that many developers, especially those new to microservices or AWS, might not possess. Option B directly addresses this by requesting an explanation and concrete instructions – the core need for clarity in documentation. Options A and C are simply affirming positive aspects or asking for visual aids without addressing the fundamental lack of understanding. Option D is a possible assumption but doesn't offer a constructive solution.
11 / 45
David: "Hey team, I'm trying to implement this new feature based on the tutorial. It's supposed to automatically handle user authentication, but it keeps throwing a 401 Unauthorized error. The tutorial just says 'Configure your authentication middleware.' That's not helpful!" Which of the following is the BEST response David should give his teammate,
Sarah, who wrote the tutorial?David is frustrated because the tutorial offers no concrete advice for troubleshooting a common error. The core issue isn't necessarily that 'configure authentication middleware' is *wrong*, but rather that it doesn't offer guidance on *how* to do so or what specific errors might indicate. A good tutorial should anticipate potential issues and provide debugging steps, not just present instructions without context. This highlights the importance of including common error scenarios and their resolutions within developer documentation.
12 / 45
John: "Hey team, I'm writing a tutorial on deploying Docker containers to Kubernetes. The current draft says: 'Set up your kubectl configuration.' It's incredibly vague – what do they actually *mean*? Should I include detailed steps on installing `kubectl` and configuring the cluster context?"John's question highlights a common issue in tutorial writing: assuming the reader has a baseline level of knowledge. While it *is* appropriate to seek clarification, his phrasing indicates he's struggling with the basic requirements. The correct answer acknowledges this – a good developer relation exercise should teach that detailed instructions are often necessary when users encounter vagueness and need concrete guidance on *how* to achieve the stated goal. Over-engineering a tutorial by adding irrelevant steps is also a common mistake.13 / 45
Daniel: "Hey team, I'm following the tutorial for setting up our new CI/CD pipeline. It says, 'Trigger a build on every push to the main branch.' But I'm not sure how that actually works – does it automatically run tests and deploy? The tutorial doesn't explain what 'triggering a build' entails."This question assesses understanding of user expectations in a tutorial. While screenshots can be helpful, simply stating the command is insufficient without context. The core issue here is that users need to understand *what* 'triggering a build' actually *does*. A good explanation would break down the process and highlight what follows from initiating it – this prevents the reader from assuming they just run a command and everything happens automatically.
14 / 45
PR Description:
Subject: Fix: Resolve NullPointerException in UserProfileService when fetching profile by ID.
Details:
This PR addresses a critical NullPointerException that occurs within the `UserProfileService` during retrieval of user profiles based on their unique identifier. The issue was triggered when the database returned a null value for the userId field, which wasn't properly handled in the service logic leading to a crash.
The fix involves adding a null check before accessing the userId property, ensuring that the code gracefully handles this scenario and avoids the exception. Comprehensive unit tests have been implemented to verify the correctness of the solution.
@john.doe @jane.smithThis question assesses understanding of effective PR descriptions. The incorrect options either lack crucial details (option 1), provide overly technical explanations (option 2) or are excessively verbose (option 3). The correct answer highlights that a good description summarizes the problem, explains the fix, and includes relevant contact information – mirroring best practices for developer communication. A clear PR description helps reviewers quickly grasp the changes and their importance.
15 / 45
You're reviewing a tutorial for setting up a new microservice. The tutorial provides a section on deploying the service to AWS ECS. One of the steps reads: 'Configure your IAM role with appropriate permissions.' The tutorial doesn't explain what an IAM role is, nor does it provide any guidance on creating or configuring one. What's the MOST helpful comment you should leave on this step for the author?
Option A: 'This is great! It clearly outlines the necessary steps to deploy.'
Option B: 'Could you add a brief explanation of what an IAM role is and provide instructions on creating one with the required permissions for accessing AWS resources?'
Option C: 'The tutorial should include screenshots showing the exact configuration settings needed in the AWS console.'
Option D: 'This step assumes the user already has experience with AWS, which isn't always the case.'
Option A: 'This is great! It clearly outlines the necessary steps to deploy.'
Option B: 'Could you add a brief explanation of what an IAM role is and provide instructions on creating one with the required permissions for accessing AWS resources?'
Option C: 'The tutorial should include screenshots showing the exact configuration settings needed in the AWS console.'
Option D: 'This step assumes the user already has experience with AWS, which isn't always the case.'
The author's instruction is too vague and assumes a level of knowledge (IAM roles) that many developers, especially those new to microservices or AWS, might not possess. Option B directly addresses this by requesting an explanation and concrete instructions – the core need for clarity in documentation. Options A and C are simply affirming positive aspects or asking for visual aids without addressing the fundamental lack of understanding. Option D is a possible assumption but doesn't offer a constructive solution.
16 / 45
David: "Hey team, I'm trying to implement this new feature based on the tutorial. It's supposed to automatically handle user authentication, but it keeps throwing a 401 Unauthorized error. The tutorial just says 'Configure your authentication middleware.' That's not helpful!" Which of the following is the BEST response David should give his teammate,
Sarah, who wrote the tutorial?David is frustrated because the tutorial offers no concrete advice for troubleshooting a common error. The core issue isn't necessarily that 'configure authentication middleware' is *wrong*, but rather that it doesn't offer guidance on *how* to do so or what specific errors might indicate. A good tutorial should anticipate potential issues and provide debugging steps, not just present instructions without context. This highlights the importance of including common error scenarios and their resolutions within developer documentation.
17 / 45
John: "Hey team, I'm writing a tutorial on deploying Docker containers to Kubernetes. The current draft says: 'Set up your kubectl configuration.' It's incredibly vague – what do they actually *mean*? Should I include detailed steps on installing `kubectl` and configuring the cluster context?"John's question highlights a common issue in tutorial writing: assuming the reader has a baseline level of knowledge. While it *is* appropriate to seek clarification, his phrasing indicates he's struggling with the basic requirements. The correct answer acknowledges this – a good developer relation exercise should teach that detailed instructions are often necessary when users encounter vagueness and need concrete guidance on *how* to achieve the stated goal. Over-engineering a tutorial by adding irrelevant steps is also a common mistake.18 / 45
Daniel: "Hey team, I'm following the tutorial for setting up our new CI/CD pipeline. It says, 'Trigger a build on every push to the main branch.' But I'm not sure how that actually works – does it automatically run tests and deploy? The tutorial doesn't explain what 'triggering a build' entails."This question assesses understanding of user expectations in a tutorial. While screenshots can be helpful, simply stating the command is insufficient without context. The core issue here is that users need to understand *what* 'triggering a build' actually *does*. A good explanation would break down the process and highlight what follows from initiating it – this prevents the reader from assuming they just run a command and everything happens automatically.
19 / 45
PR Description:
Subject: Fix: Resolve NullPointerException in UserProfileService when fetching profile by ID.
Details:
This PR addresses a critical NullPointerException that occurs within the `UserProfileService` during retrieval of user profiles based on their unique identifier. The issue was triggered when the database returned a null value for the userId field, which wasn't properly handled in the service logic leading to a crash.
The fix involves adding a null check before accessing the userId property, ensuring that the code gracefully handles this scenario and avoids the exception. Comprehensive unit tests have been implemented to verify the correctness of the solution.
@john.doe @jane.smithThis question assesses understanding of effective PR descriptions. The incorrect options either lack crucial details (option 1), provide overly technical explanations (option 2) or are excessively verbose (option 3). The correct answer highlights that a good description summarizes the problem, explains the fix, and includes relevant contact information – mirroring best practices for developer communication. A clear PR description helps reviewers quickly grasp the changes and their importance.
20 / 45
You're reviewing a tutorial for setting up a new microservice. The tutorial provides a section on deploying the service to AWS ECS. One of the steps reads: 'Configure your IAM role with appropriate permissions.' The tutorial doesn't explain what an IAM role is, nor does it provide any guidance on creating or configuring one. What's the MOST helpful comment you should leave on this step for the author?
Option A: 'This is great! It clearly outlines the necessary steps to deploy.'
Option B: 'Could you add a brief explanation of what an IAM role is and provide instructions on creating one with the required permissions for accessing AWS resources?'
Option C: 'The tutorial should include screenshots showing the exact configuration settings needed in the AWS console.'
Option D: 'This step assumes the user already has experience with AWS, which isn't always the case.'
Option A: 'This is great! It clearly outlines the necessary steps to deploy.'
Option B: 'Could you add a brief explanation of what an IAM role is and provide instructions on creating one with the required permissions for accessing AWS resources?'
Option C: 'The tutorial should include screenshots showing the exact configuration settings needed in the AWS console.'
Option D: 'This step assumes the user already has experience with AWS, which isn't always the case.'
The author's instruction is too vague and assumes a level of knowledge (IAM roles) that many developers, especially those new to microservices or AWS, might not possess. Option B directly addresses this by requesting an explanation and concrete instructions – the core need for clarity in documentation. Options A and C are simply affirming positive aspects or asking for visual aids without addressing the fundamental lack of understanding. Option D is a possible assumption but doesn't offer a constructive solution.
21 / 45
David: "Hey team, I'm trying to implement this new feature based on the tutorial. It's supposed to automatically handle user authentication, but it keeps throwing a 401 Unauthorized error. The tutorial just says 'Configure your authentication middleware.' That's not helpful!" Which of the following is the BEST response David should give his teammate,
Sarah, who wrote the tutorial?David is frustrated because the tutorial offers no concrete advice for troubleshooting a common error. The core issue isn't necessarily that 'configure authentication middleware' is *wrong*, but rather that it doesn't offer guidance on *how* to do so or what specific errors might indicate. A good tutorial should anticipate potential issues and provide debugging steps, not just present instructions without context. This highlights the importance of including common error scenarios and their resolutions within developer documentation.
22 / 45
John: "Hey team, I'm writing a tutorial on deploying Docker containers to Kubernetes. The current draft says: 'Set up your kubectl configuration.' It's incredibly vague – what do they actually *mean*? Should I include detailed steps on installing `kubectl` and configuring the cluster context?"John's question highlights a common issue in tutorial writing: assuming the reader has a baseline level of knowledge. While it *is* appropriate to seek clarification, his phrasing indicates he's struggling with the basic requirements. The correct answer acknowledges this – a good developer relation exercise should teach that detailed instructions are often necessary when users encounter vagueness and need concrete guidance on *how* to achieve the stated goal. Over-engineering a tutorial by adding irrelevant steps is also a common mistake.23 / 45
Daniel: "Hey team, I'm following the tutorial for setting up our new CI/CD pipeline. It says, 'Trigger a build on every push to the main branch.' But I'm not sure how that actually works – does it automatically run tests and deploy? The tutorial doesn't explain what 'triggering a build' entails."This question assesses understanding of user expectations in a tutorial. While screenshots can be helpful, simply stating the command is insufficient without context. The core issue here is that users need to understand *what* 'triggering a build' actually *does*. A good explanation would break down the process and highlight what follows from initiating it – this prevents the reader from assuming they just run a command and everything happens automatically.
24 / 45
PR Description:
Subject: Fix: Resolve NullPointerException in UserProfileService when fetching profile by ID.
Details:
This PR addresses a critical NullPointerException that occurs within the `UserProfileService` during retrieval of user profiles based on their unique identifier. The issue was triggered when the database returned a null value for the userId field, which wasn't properly handled in the service logic leading to a crash.
The fix involves adding a null check before accessing the userId property, ensuring that the code gracefully handles this scenario and avoids the exception. Comprehensive unit tests have been implemented to verify the correctness of the solution.
@john.doe @jane.smithThis question assesses understanding of effective PR descriptions. The incorrect options either lack crucial details (option 1), provide overly technical explanations (option 2) or are excessively verbose (option 3). The correct answer highlights that a good description summarizes the problem, explains the fix, and includes relevant contact information – mirroring best practices for developer communication. A clear PR description helps reviewers quickly grasp the changes and their importance.
25 / 45
You're reviewing a tutorial for setting up a new microservice. The tutorial provides a section on deploying the service to AWS ECS. One of the steps reads: 'Configure your IAM role with appropriate permissions.' The tutorial doesn't explain what an IAM role is, nor does it provide any guidance on creating or configuring one. What's the MOST helpful comment you should leave on this step for the author?
Option A: 'This is great! It clearly outlines the necessary steps to deploy.'
Option B: 'Could you add a brief explanation of what an IAM role is and provide instructions on creating one with the required permissions for accessing AWS resources?'
Option C: 'The tutorial should include screenshots showing the exact configuration settings needed in the AWS console.'
Option D: 'This step assumes the user already has experience with AWS, which isn't always the case.'
Option A: 'This is great! It clearly outlines the necessary steps to deploy.'
Option B: 'Could you add a brief explanation of what an IAM role is and provide instructions on creating one with the required permissions for accessing AWS resources?'
Option C: 'The tutorial should include screenshots showing the exact configuration settings needed in the AWS console.'
Option D: 'This step assumes the user already has experience with AWS, which isn't always the case.'
The author's instruction is too vague and assumes a level of knowledge (IAM roles) that many developers, especially those new to microservices or AWS, might not possess. Option B directly addresses this by requesting an explanation and concrete instructions – the core need for clarity in documentation. Options A and C are simply affirming positive aspects or asking for visual aids without addressing the fundamental lack of understanding. Option D is a possible assumption but doesn't offer a constructive solution.
26 / 45
David: "Hey team, I'm trying to implement this new feature based on the tutorial. It's supposed to automatically handle user authentication, but it keeps throwing a 401 Unauthorized error. The tutorial just says 'Configure your authentication middleware.' That's not helpful!" Which of the following is the BEST response David should give his teammate,
Sarah, who wrote the tutorial?David is frustrated because the tutorial offers no concrete advice for troubleshooting a common error. The core issue isn't necessarily that 'configure authentication middleware' is *wrong*, but rather that it doesn't offer guidance on *how* to do so or what specific errors might indicate. A good tutorial should anticipate potential issues and provide debugging steps, not just present instructions without context. This highlights the importance of including common error scenarios and their resolutions within developer documentation.
27 / 45
John: "Hey team, I'm writing a tutorial on deploying Docker containers to Kubernetes. The current draft says: 'Set up your kubectl configuration.' It's incredibly vague – what do they actually *mean*? Should I include detailed steps on installing `kubectl` and configuring the cluster context?"John's question highlights a common issue in tutorial writing: assuming the reader has a baseline level of knowledge. While it *is* appropriate to seek clarification, his phrasing indicates he's struggling with the basic requirements. The correct answer acknowledges this – a good developer relation exercise should teach that detailed instructions are often necessary when users encounter vagueness and need concrete guidance on *how* to achieve the stated goal. Over-engineering a tutorial by adding irrelevant steps is also a common mistake.28 / 45
Daniel: "Hey team, I'm following the tutorial for setting up our new CI/CD pipeline. It says, 'Trigger a build on every push to the main branch.' But I'm not sure how that actually works – does it automatically run tests and deploy? The tutorial doesn't explain what 'triggering a build' entails."This question assesses understanding of user expectations in a tutorial. While screenshots can be helpful, simply stating the command is insufficient without context. The core issue here is that users need to understand *what* 'triggering a build' actually *does*. A good explanation would break down the process and highlight what follows from initiating it – this prevents the reader from assuming they just run a command and everything happens automatically.
29 / 45
PR Description:
Subject: Fix: Resolve NullPointerException in UserProfileService when fetching profile by ID.
Details:
This PR addresses a critical NullPointerException that occurs within the `UserProfileService` during retrieval of user profiles based on their unique identifier. The issue was triggered when the database returned a null value for the userId field, which wasn't properly handled in the service logic leading to a crash.
The fix involves adding a null check before accessing the userId property, ensuring that the code gracefully handles this scenario and avoids the exception. Comprehensive unit tests have been implemented to verify the correctness of the solution.
@john.doe @jane.smithThis question assesses understanding of effective PR descriptions. The incorrect options either lack crucial details (option 1), provide overly technical explanations (option 2) or are excessively verbose (option 3). The correct answer highlights that a good description summarizes the problem, explains the fix, and includes relevant contact information – mirroring best practices for developer communication. A clear PR description helps reviewers quickly grasp the changes and their importance.
30 / 45
You're reviewing a tutorial for setting up a new microservice. The tutorial provides a section on deploying the service to AWS ECS. One of the steps reads: 'Configure your IAM role with appropriate permissions.' The tutorial doesn't explain what an IAM role is, nor does it provide any guidance on creating or configuring one. What's the MOST helpful comment you should leave on this step for the author?
Option A: 'This is great! It clearly outlines the necessary steps to deploy.'
Option B: 'Could you add a brief explanation of what an IAM role is and provide instructions on creating one with the required permissions for accessing AWS resources?'
Option C: 'The tutorial should include screenshots showing the exact configuration settings needed in the AWS console.'
Option D: 'This step assumes the user already has experience with AWS, which isn't always the case.'
Option A: 'This is great! It clearly outlines the necessary steps to deploy.'
Option B: 'Could you add a brief explanation of what an IAM role is and provide instructions on creating one with the required permissions for accessing AWS resources?'
Option C: 'The tutorial should include screenshots showing the exact configuration settings needed in the AWS console.'
Option D: 'This step assumes the user already has experience with AWS, which isn't always the case.'
The author's instruction is too vague and assumes a level of knowledge (IAM roles) that many developers, especially those new to microservices or AWS, might not possess. Option B directly addresses this by requesting an explanation and concrete instructions – the core need for clarity in documentation. Options A and C are simply affirming positive aspects or asking for visual aids without addressing the fundamental lack of understanding. Option D is a possible assumption but doesn't offer a constructive solution.
31 / 45
David: "Hey team, I'm trying to implement this new feature based on the tutorial. It's supposed to automatically handle user authentication, but it keeps throwing a 401 Unauthorized error. The tutorial just says 'Configure your authentication middleware.' That's not helpful!" Which of the following is the BEST response David should give his teammate,
Sarah, who wrote the tutorial?David is frustrated because the tutorial offers no concrete advice for troubleshooting a common error. The core issue isn't necessarily that 'configure authentication middleware' is *wrong*, but rather that it doesn't offer guidance on *how* to do so or what specific errors might indicate. A good tutorial should anticipate potential issues and provide debugging steps, not just present instructions without context. This highlights the importance of including common error scenarios and their resolutions within developer documentation.
32 / 45
John: "Hey team, I'm writing a tutorial on deploying Docker containers to Kubernetes. The current draft says: 'Set up your kubectl configuration.' It's incredibly vague – what do they actually *mean*? Should I include detailed steps on installing `kubectl` and configuring the cluster context?"John's question highlights a common issue in tutorial writing: assuming the reader has a baseline level of knowledge. While it *is* appropriate to seek clarification, his phrasing indicates he's struggling with the basic requirements. The correct answer acknowledges this – a good developer relation exercise should teach that detailed instructions are often necessary when users encounter vagueness and need concrete guidance on *how* to achieve the stated goal. Over-engineering a tutorial by adding irrelevant steps is also a common mistake.33 / 45
Daniel: "Hey team, I'm following the tutorial for setting up our new CI/CD pipeline. It says, 'Trigger a build on every push to the main branch.' But I'm not sure how that actually works – does it automatically run tests and deploy? The tutorial doesn't explain what 'triggering a build' entails."This question assesses understanding of user expectations in a tutorial. While screenshots can be helpful, simply stating the command is insufficient without context. The core issue here is that users need to understand *what* 'triggering a build' actually *does*. A good explanation would break down the process and highlight what follows from initiating it – this prevents the reader from assuming they just run a command and everything happens automatically.
34 / 45
PR Description:
Subject: Fix: Resolve NullPointerException in UserProfileService when fetching profile by ID.
Details:
This PR addresses a critical NullPointerException that occurs within the `UserProfileService` during retrieval of user profiles based on their unique identifier. The issue was triggered when the database returned a null value for the userId field, which wasn't properly handled in the service logic leading to a crash.
The fix involves adding a null check before accessing the userId property, ensuring that the code gracefully handles this scenario and avoids the exception. Comprehensive unit tests have been implemented to verify the correctness of the solution.
@john.doe @jane.smithThis question assesses understanding of effective PR descriptions. The incorrect options either lack crucial details (option 1), provide overly technical explanations (option 2) or are excessively verbose (option 3). The correct answer highlights that a good description summarizes the problem, explains the fix, and includes relevant contact information – mirroring best practices for developer communication. A clear PR description helps reviewers quickly grasp the changes and their importance.
35 / 45
You're reviewing a tutorial for setting up a new microservice. The tutorial provides a section on deploying the service to AWS ECS. One of the steps reads: 'Configure your IAM role with appropriate permissions.' The tutorial doesn't explain what an IAM role is, nor does it provide any guidance on creating or configuring one. What's the MOST helpful comment you should leave on this step for the author?
Option A: 'This is great! It clearly outlines the necessary steps to deploy.'
Option B: 'Could you add a brief explanation of what an IAM role is and provide instructions on creating one with the required permissions for accessing AWS resources?'
Option C: 'The tutorial should include screenshots showing the exact configuration settings needed in the AWS console.'
Option D: 'This step assumes the user already has experience with AWS, which isn't always the case.'
Option A: 'This is great! It clearly outlines the necessary steps to deploy.'
Option B: 'Could you add a brief explanation of what an IAM role is and provide instructions on creating one with the required permissions for accessing AWS resources?'
Option C: 'The tutorial should include screenshots showing the exact configuration settings needed in the AWS console.'
Option D: 'This step assumes the user already has experience with AWS, which isn't always the case.'
The author's instruction is too vague and assumes a level of knowledge (IAM roles) that many developers, especially those new to microservices or AWS, might not possess. Option B directly addresses this by requesting an explanation and concrete instructions – the core need for clarity in documentation. Options A and C are simply affirming positive aspects or asking for visual aids without addressing the fundamental lack of understanding. Option D is a possible assumption but doesn't offer a constructive solution.
36 / 45
David: "Hey team, I'm trying to implement this new feature based on the tutorial. It's supposed to automatically handle user authentication, but it keeps throwing a 401 Unauthorized error. The tutorial just says 'Configure your authentication middleware.' That's not helpful!" Which of the following is the BEST response David should give his teammate,
Sarah, who wrote the tutorial?David is frustrated because the tutorial offers no concrete advice for troubleshooting a common error. The core issue isn't necessarily that 'configure authentication middleware' is *wrong*, but rather that it doesn't offer guidance on *how* to do so or what specific errors might indicate. A good tutorial should anticipate potential issues and provide debugging steps, not just present instructions without context. This highlights the importance of including common error scenarios and their resolutions within developer documentation.
37 / 45
John: "Hey team, I'm writing a tutorial on deploying Docker containers to Kubernetes. The current draft says: 'Set up your kubectl configuration.' It's incredibly vague – what do they actually *mean*? Should I include detailed steps on installing `kubectl` and configuring the cluster context?"John's question highlights a common issue in tutorial writing: assuming the reader has a baseline level of knowledge. While it *is* appropriate to seek clarification, his phrasing indicates he's struggling with the basic requirements. The correct answer acknowledges this – a good developer relation exercise should teach that detailed instructions are often necessary when users encounter vagueness and need concrete guidance on *how* to achieve the stated goal. Over-engineering a tutorial by adding irrelevant steps is also a common mistake.38 / 45
Daniel: "Hey team, I'm following the tutorial for setting up our new CI/CD pipeline. It says, 'Trigger a build on every push to the main branch.' But I'm not sure how that actually works – does it automatically run tests and deploy? The tutorial doesn't explain what 'triggering a build' entails."This question assesses understanding of user expectations in a tutorial. While screenshots can be helpful, simply stating the command is insufficient without context. The core issue here is that users need to understand *what* 'triggering a build' actually *does*. A good explanation would break down the process and highlight what follows from initiating it – this prevents the reader from assuming they just run a command and everything happens automatically.
39 / 45
PR Description:
Subject: Fix: Resolve NullPointerException in UserProfileService when fetching profile by ID.
Details:
This PR addresses a critical NullPointerException that occurs within the `UserProfileService` during retrieval of user profiles based on their unique identifier. The issue was triggered when the database returned a null value for the userId field, which wasn't properly handled in the service logic leading to a crash.
The fix involves adding a null check before accessing the userId property, ensuring that the code gracefully handles this scenario and avoids the exception. Comprehensive unit tests have been implemented to verify the correctness of the solution.
@john.doe @jane.smithThis question assesses understanding of effective PR descriptions. The incorrect options either lack crucial details (option 1), provide overly technical explanations (option 2) or are excessively verbose (option 3). The correct answer highlights that a good description summarizes the problem, explains the fix, and includes relevant contact information – mirroring best practices for developer communication. A clear PR description helps reviewers quickly grasp the changes and their importance.
40 / 45
You're reviewing a tutorial for setting up a new microservice. The tutorial provides a section on deploying the service to AWS ECS. One of the steps reads: 'Configure your IAM role with appropriate permissions.' The tutorial doesn't explain what an IAM role is, nor does it provide any guidance on creating or configuring one. What's the MOST helpful comment you should leave on this step for the author?
Option A: 'This is great! It clearly outlines the necessary steps to deploy.'
Option B: 'Could you add a brief explanation of what an IAM role is and provide instructions on creating one with the required permissions for accessing AWS resources?'
Option C: 'The tutorial should include screenshots showing the exact configuration settings needed in the AWS console.'
Option D: 'This step assumes the user already has experience with AWS, which isn't always the case.'
Option A: 'This is great! It clearly outlines the necessary steps to deploy.'
Option B: 'Could you add a brief explanation of what an IAM role is and provide instructions on creating one with the required permissions for accessing AWS resources?'
Option C: 'The tutorial should include screenshots showing the exact configuration settings needed in the AWS console.'
Option D: 'This step assumes the user already has experience with AWS, which isn't always the case.'
The author's instruction is too vague and assumes a level of knowledge (IAM roles) that many developers, especially those new to microservices or AWS, might not possess. Option B directly addresses this by requesting an explanation and concrete instructions – the core need for clarity in documentation. Options A and C are simply affirming positive aspects or asking for visual aids without addressing the fundamental lack of understanding. Option D is a possible assumption but doesn't offer a constructive solution.
41 / 45
David: "Hey team, I'm trying to implement this new feature based on the tutorial. It's supposed to automatically handle user authentication, but it keeps throwing a 401 Unauthorized error. The tutorial just says 'Configure your authentication middleware.' That's not helpful!" Which of the following is the BEST response David should give his teammate,
Sarah, who wrote the tutorial?David is frustrated because the tutorial offers no concrete advice for troubleshooting a common error. The core issue isn't necessarily that 'configure authentication middleware' is *wrong*, but rather that it doesn't offer guidance on *how* to do so or what specific errors might indicate. A good tutorial should anticipate potential issues and provide debugging steps, not just present instructions without context. This highlights the importance of including common error scenarios and their resolutions within developer documentation.
42 / 45
John: "Hey team, I'm writing a tutorial on deploying Docker containers to Kubernetes. The current draft says: 'Set up your kubectl configuration.' It's incredibly vague – what do they actually *mean*? Should I include detailed steps on installing `kubectl` and configuring the cluster context?"John's question highlights a common issue in tutorial writing: assuming the reader has a baseline level of knowledge. While it *is* appropriate to seek clarification, his phrasing indicates he's struggling with the basic requirements. The correct answer acknowledges this – a good developer relation exercise should teach that detailed instructions are often necessary when users encounter vagueness and need concrete guidance on *how* to achieve the stated goal. Over-engineering a tutorial by adding irrelevant steps is also a common mistake.43 / 45
Daniel: "Hey team, I'm following the tutorial for setting up our new CI/CD pipeline. It says, 'Trigger a build on every push to the main branch.' But I'm not sure how that actually works – does it automatically run tests and deploy? The tutorial doesn't explain what 'triggering a build' entails."This question assesses understanding of user expectations in a tutorial. While screenshots can be helpful, simply stating the command is insufficient without context. The core issue here is that users need to understand *what* 'triggering a build' actually *does*. A good explanation would break down the process and highlight what follows from initiating it – this prevents the reader from assuming they just run a command and everything happens automatically.
44 / 45
PR Description:
Subject: Fix: Resolve NullPointerException in UserProfileService when fetching profile by ID.
Details:
This PR addresses a critical NullPointerException that occurs within the `UserProfileService` during retrieval of user profiles based on their unique identifier. The issue was triggered when the database returned a null value for the userId field, which wasn't properly handled in the service logic leading to a crash.
The fix involves adding a null check before accessing the userId property, ensuring that the code gracefully handles this scenario and avoids the exception. Comprehensive unit tests have been implemented to verify the correctness of the solution.
@john.doe @jane.smithThis question assesses understanding of effective PR descriptions. The incorrect options either lack crucial details (option 1), provide overly technical explanations (option 2) or are excessively verbose (option 3). The correct answer highlights that a good description summarizes the problem, explains the fix, and includes relevant contact information – mirroring best practices for developer communication. A clear PR description helps reviewers quickly grasp the changes and their importance.
45 / 45
You're reviewing a tutorial for setting up a new microservice. The tutorial provides a section on deploying the service to AWS ECS. One of the steps reads: 'Configure your IAM role with appropriate permissions.' The tutorial doesn't explain what an IAM role is, nor does it provide any guidance on creating or configuring one. What's the MOST helpful comment you should leave on this step for the author?
Option A: 'This is great! It clearly outlines the necessary steps to deploy.'
Option B: 'Could you add a brief explanation of what an IAM role is and provide instructions on creating one with the required permissions for accessing AWS resources?'
Option C: 'The tutorial should include screenshots showing the exact configuration settings needed in the AWS console.'
Option D: 'This step assumes the user already has experience with AWS, which isn't always the case.'
Option A: 'This is great! It clearly outlines the necessary steps to deploy.'
Option B: 'Could you add a brief explanation of what an IAM role is and provide instructions on creating one with the required permissions for accessing AWS resources?'
Option C: 'The tutorial should include screenshots showing the exact configuration settings needed in the AWS console.'
Option D: 'This step assumes the user already has experience with AWS, which isn't always the case.'
The author's instruction is too vague and assumes a level of knowledge (IAM roles) that many developers, especially those new to microservices or AWS, might not possess. Option B directly addresses this by requesting an explanation and concrete instructions – the core need for clarity in documentation. Options A and C are simply affirming positive aspects or asking for visual aids without addressing the fundamental lack of understanding. Option D is a possible assumption but doesn't offer a constructive solution.
Frequently Asked Questions
What does the "Tutorial Writing — Developer Relations English Exercises" exercise cover?
Practice English for writing developer tutorials: prerequisites, atomic steps, error handling, checkpoints, and strong conclusions.
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 "Tutorial Writing — Developer Relations English 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 Developer Relations exercises?
Browse the full Developer Relations 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.