5 exercises — Master documentation vocabulary: reference vs. guide vs. tutorial, API doc anti-patterns, documentation debt, docs-as-code workflows, and progressive disclosure.
0 / 26 completed
1 / 26
A new engineer asks: "Someone told me to check the 'reference docs' but then also look at the 'guide.' What's the difference?" Which answer is correct?
The four main documentation types each serve a distinct purpose — knowing which to use prevents wasted reading time.
The Diátaxis framework defines four documentation types:
• Reference — factual descriptions; consulted, not read linearly (API docs, parameter lists)
• How-to guides — goal-oriented, step-by-step; assumes reader knows the goal (recipes, installation guides)
• Tutorials — learning-oriented; reader builds something working from scratch, learns by doing
• Explanations / Concepts — understanding-oriented; explains why, not how (architecture overviews, design decisions)
Why the distinction matters:
• If you send a beginner to reference docs, they don't have enough context yet = frustration
• If you send an expert to a tutorial, they don't want the learning scaffolding = wasted time
• Finding the right doc type for the right use case is a DevRel skill
Key vocabulary:
• Reference documentation — precise, complete descriptions of a system's components and behavior
• How-to guide — a goal-oriented document that walks through accomplishing a specific task
• Tutorial — a learning-oriented document where the reader does something to acquire new skills
• Conceptual documentation — explanations of how and why a system works, not how to use it
• Diátaxis framework — a documentation structure framework by Daniele Procida organizing docs by purpose
2 / 26
A developer reads an API parameter description: "The timeout parameter specifies the timeout." What documentation anti-pattern is this?
A circular definition (also called a tautology) restates the term without explaining it — the reader is no better off than before reading.
Circular: "The timeout parameter specifies the timeout."
Non-circular: "The timeout parameter specifies how many milliseconds to wait for a server response before the request is cancelled and returns a TIMEOUT_ERROR. Defaults to 30000 (30 seconds)."
What the non-circular version adds:
• Unit — "milliseconds" (not seconds? not micro-seconds?)
• What happens at timeout — "request is cancelled and returns TIMEOUT_ERROR"
• Default value — "Defaults to 30000 (30 seconds)" (necessary to reason about the parameter)
Common API doc anti-patterns:
• Circular definition — "title is the title of the item"
• Missing unit — "delay: 500" (500 what?)
• Missing default — "optional parameter" (what happens if I omit it?)
• Missing error behavior — "what if I pass -1?"
Key vocabulary:
• Circular definition — a definition that uses the word it defines as part of the explanation
• Parameter description — the documentation for a single function or API parameter
• Default value — the value used when a parameter is not explicitly provided
• Boundary conditions — the behavior at the limits of a parameter's valid range
• API reference documentation — complete, precise descriptions of every parameter, method, and return value
3 / 26
A team lead says: "We have documentation debt." What does this mean?
Documentation debt is the documentation analog of technical debt — the cost of work deferred that accumulates over time.
Common forms of documentation debt:
• Outdated docs — code changed but docs still describe the old behavior
• Missing docs — shipped features with no documentation
• Misleading docs — docs that are technically accurate but lead developers to wrong conclusions
• Stale examples — code samples that no longer compile or run against the current version
• Broken links — references to documentation pages that no longer exist
Why documentation debt compounds:
• Every developer who hits a wrong doc creates a support ticket
• Every support ticket that isn't fixed in docs gets asked again
• The older the wrong doc, the harder it is to find and fix (no one owns it)
The analogy to technical debt is intentional — both represent deferred work with compounding interest in support costs and developer frustration.
Key vocabulary:
• Documentation debt — the accumulated cost of deferred documentation work
• Stale documentation — documentation that was once accurate but is no longer correct
• Docs rot — informal term for documentation that degrades over time without active maintenance
• Technical debt — accumulated shortcuts in code that require future work to fix
• Documentation audit — a systematic review of existing documentation for accuracy and completeness
4 / 26
A developer advocate says: "We use a docs-as-code workflow." What does this mean?
Docs-as-code is a documentation methodology that applies software engineering practices to documentation creation and maintenance.
Core elements of docs-as-code:
• Markup language — Markdown or AsciiDoc (not Word or Confluence WYSIWYG)
• Version control — documentation stored in Git alongside the code it documents
• Pull request workflow — documentation changes reviewed like code changes
• CI/CD deployment — docs automatically built and deployed when merged (using tools like Docusaurus, MkDocs, Sphinx)
• Tests for docs — link checkers, code sample validation, spelling/style linters
Why docs-as-code solves common problems:
• Docs stay in sync with code — they live in the same repo, in the same PR
• Same review process — engineers don't need a separate tool to critique docs
• History and blame — git log shows who changed what and when
• Rollback — documentation mistakes can be reverted like code mistakes
Key vocabulary:
• Docs-as-code — treating documentation like software: versioned, reviewed, and deployed through engineering workflows
• Markdown — a lightweight markup language commonly used in docs-as-code workflows
• Static site generator (SSG) — a tool that converts Markdown docs into a hosted website (Docusaurus, MkDocs, Astro)
• Documentation CI/CD — automated pipelines that build, test, and deploy documentation
• Co-located documentation — documentation stored in the same repository as the code it describes
5 / 26
A technical writer uses the phrase "progressive disclosure" when reviewing API documentation design. What does it mean?
Progressive disclosure is an information design principle: show essential information first, provide depth on request or via progressive navigation.
Applied to API documentation:
• First level — simple, common example (copy-paste ready, annotated inline)
• Second level — expandable parameters section with all options and defaults
• Third level — deep conceptual explanation link for users who need to understand internals
Example in practice:
Stripe's API docs show the minimal code example first, then expandable sections for optional parameters, then a separate "how payments work" conceptual guide — three levels of disclosure, each optional.
Why it matters for DevRel:
• A beginner sees the working example and ships; the advanced override section doesn't confuse them
• An expert can expand to see all parameters without wading through beginner scaffolding
• Cognitive overload from too much upfront information is one of the top causes of developer abandonment
Key vocabulary:
• Progressive disclosure — presenting information in layers, from essential to complex
• Cognitive load — the mental effort required to understand a piece of documentation
• Developer experience (DX) — the holistic quality of a developer's journey through a tool, including its documentation
• Annotated code sample — a code example with inline explanations of what each line does
• Documentation information architecture — the structural organization of a documentation site
6 / 26
Sarah: 'The API response is returning a 400 error. I checked the documentation, but it doesn't explicitly say what constitutes an invalid request format. It just mentions 'JSON compliance.' What should I do next?', (Slack message during code review)
The documentation's statement about 'JSON compliance' is vague and doesn't provide actionable guidance. Sarah needs to proactively seek more specific information. Requesting clarification from the design team will help pinpoint the exact JSON schema requirements – data types, field names, and any validation rules beyond a basic JSON structure. Simply returning valid JSON isn't enough; the API might have stringent constraints that aren't detailed in the initial documentation.
7 / 26
David: "Hey team, I'm getting a lot of pushback on the new authentication flow. The documentation says 'use OAuth 2.0,' but it doesn't really *explain* how to integrate with Auth0 – just links to their broader docs. It feels like we're expected to figure this out ourselves! Should I flag this as a gap?", (PR description for a feature adding new authentication)
This scenario highlights a critical problem: documentation doesn't always bridge the gap between high-level specifications (like 'use OAuth 2.0') and practical implementation details. David is right to feel frustrated – good developer documentation should provide concrete examples and guidance for common integration scenarios, especially when using third-party services like Auth0. Pointing out this lack of specific instructions within the PR description is a valuable contribution to improving the overall quality and usability of the documentation.
8 / 26
Mark: 'I'm reviewing this PR and the `calculate_discount` function uses a constant value for the 'tax rate.' The documentation for the API states that the 'tax_rate' parameter should be dynamically determined based on the user's location. I've flagged it as a potential issue, but the developer says they just thought it was simpler this way. What is Mark's primary concern regarding this situation, and how best to address it within a code review context?
Mark's primary concern is that the developer isn't adhering to documented API specifications. While rapid prototyping can be valuable, consistently deviating from established documentation patterns creates 'documentation debt,' which makes future updates and maintenance significantly more difficult and increases the risk of errors. The correct response involves gently but firmly pointing out the discrepancy and emphasizing the importance of following the defined API contract for consistency and maintainability.
9 / 26
John is reviewing a PR that uses an external library. He notices the documentation for the library's `fetchData` function states: 'This function accepts a single string argument representing the URL to fetch.' However, the code within the PR passes the entire JSON object as a string. John suspects this might be incorrect. Which of the following is his MOST appropriate next step during the code review?
John's primary concern is whether the code is *actually* using the API correctly. Option A is too forceful – developers sometimes have valid reasons for deviating from strict documentation if they understand the underlying functionality. Option C is a reactive approach; John should first try to understand the developer's reasoning. Option B is the most proactive, encouraging the developer to clarify any ambiguities and ensure compatibility with the library's intended usage. Option D is risky – accepting deviations without understanding them could lead to future problems.
10 / 26
Sarah: 'The API response is returning a 400 error. I checked the documentation, but it doesn't explicitly say what constitutes an invalid request format. It just mentions 'JSON compliance.' What should I do next?', (Slack message during code review)
The documentation's statement about 'JSON compliance' is vague and doesn't provide actionable guidance. Sarah needs to proactively seek more specific information. Requesting clarification from the design team will help pinpoint the exact JSON schema requirements – data types, field names, and any validation rules beyond a basic JSON structure. Simply returning valid JSON isn't enough; the API might have stringent constraints that aren't detailed in the initial documentation.
11 / 26
David: "Hey team, I'm getting a lot of pushback on the new authentication flow. The documentation says 'use OAuth 2.0,' but it doesn't really *explain* how to integrate with Auth0 – just links to their broader docs. It feels like we're expected to figure this out ourselves! Should I flag this as a gap?", (PR description for a feature adding new authentication)
This scenario highlights a critical problem: documentation doesn't always bridge the gap between high-level specifications (like 'use OAuth 2.0') and practical implementation details. David is right to feel frustrated – good developer documentation should provide concrete examples and guidance for common integration scenarios, especially when using third-party services like Auth0. Pointing out this lack of specific instructions within the PR description is a valuable contribution to improving the overall quality and usability of the documentation.
12 / 26
Mark: 'I'm reviewing this PR and the `calculate_discount` function uses a constant value for the 'tax rate.' The documentation for the API states that the 'tax_rate' parameter should be dynamically determined based on the user's location. I've flagged it as a potential issue, but the developer says they just thought it was simpler this way. What is Mark's primary concern regarding this situation, and how best to address it within a code review context?
Mark's primary concern is that the developer isn't adhering to documented API specifications. While rapid prototyping can be valuable, consistently deviating from established documentation patterns creates 'documentation debt,' which makes future updates and maintenance significantly more difficult and increases the risk of errors. The correct response involves gently but firmly pointing out the discrepancy and emphasizing the importance of following the defined API contract for consistency and maintainability.
13 / 26
John is reviewing a PR that uses an external library. He notices the documentation for the library's `fetchData` function states: 'This function accepts a single string argument representing the URL to fetch.' However, the code within the PR passes the entire JSON object as a string. John suspects this might be incorrect. Which of the following is his MOST appropriate next step during the code review?
John's primary concern is whether the code is *actually* using the API correctly. Option A is too forceful – developers sometimes have valid reasons for deviating from strict documentation if they understand the underlying functionality. Option C is a reactive approach; John should first try to understand the developer's reasoning. Option B is the most proactive, encouraging the developer to clarify any ambiguities and ensure compatibility with the library's intended usage. Option D is risky – accepting deviations without understanding them could lead to future problems.
14 / 26
Sarah: 'The API response is returning a 400 error. I checked the documentation, but it doesn't explicitly say what constitutes an invalid request format. It just mentions 'JSON compliance.' What should I do next?', (Slack message during code review)
The documentation's statement about 'JSON compliance' is vague and doesn't provide actionable guidance. Sarah needs to proactively seek more specific information. Requesting clarification from the design team will help pinpoint the exact JSON schema requirements – data types, field names, and any validation rules beyond a basic JSON structure. Simply returning valid JSON isn't enough; the API might have stringent constraints that aren't detailed in the initial documentation.
15 / 26
David: "Hey team, I'm getting a lot of pushback on the new authentication flow. The documentation says 'use OAuth 2.0,' but it doesn't really *explain* how to integrate with Auth0 – just links to their broader docs. It feels like we're expected to figure this out ourselves! Should I flag this as a gap?", (PR description for a feature adding new authentication)
This scenario highlights a critical problem: documentation doesn't always bridge the gap between high-level specifications (like 'use OAuth 2.0') and practical implementation details. David is right to feel frustrated – good developer documentation should provide concrete examples and guidance for common integration scenarios, especially when using third-party services like Auth0. Pointing out this lack of specific instructions within the PR description is a valuable contribution to improving the overall quality and usability of the documentation.
16 / 26
Mark: 'I'm reviewing this PR and the `calculate_discount` function uses a constant value for the 'tax rate.' The documentation for the API states that the 'tax_rate' parameter should be dynamically determined based on the user's location. I've flagged it as a potential issue, but the developer says they just thought it was simpler this way. What is Mark's primary concern regarding this situation, and how best to address it within a code review context?
Mark's primary concern is that the developer isn't adhering to documented API specifications. While rapid prototyping can be valuable, consistently deviating from established documentation patterns creates 'documentation debt,' which makes future updates and maintenance significantly more difficult and increases the risk of errors. The correct response involves gently but firmly pointing out the discrepancy and emphasizing the importance of following the defined API contract for consistency and maintainability.
17 / 26
John is reviewing a PR that uses an external library. He notices the documentation for the library's `fetchData` function states: 'This function accepts a single string argument representing the URL to fetch.' However, the code within the PR passes the entire JSON object as a string. John suspects this might be incorrect. Which of the following is his MOST appropriate next step during the code review?
John's primary concern is whether the code is *actually* using the API correctly. Option A is too forceful – developers sometimes have valid reasons for deviating from strict documentation if they understand the underlying functionality. Option C is a reactive approach; John should first try to understand the developer's reasoning. Option B is the most proactive, encouraging the developer to clarify any ambiguities and ensure compatibility with the library's intended usage. Option D is risky – accepting deviations without understanding them could lead to future problems.
18 / 26
Sarah: 'The API response is returning a 400 error. I checked the documentation, but it doesn't explicitly say what constitutes an invalid request format. It just mentions 'JSON compliance.' What should I do next?', (Slack message during code review)
The documentation's statement about 'JSON compliance' is vague and doesn't provide actionable guidance. Sarah needs to proactively seek more specific information. Requesting clarification from the design team will help pinpoint the exact JSON schema requirements – data types, field names, and any validation rules beyond a basic JSON structure. Simply returning valid JSON isn't enough; the API might have stringent constraints that aren't detailed in the initial documentation.
19 / 26
David: "Hey team, I'm getting a lot of pushback on the new authentication flow. The documentation says 'use OAuth 2.0,' but it doesn't really *explain* how to integrate with Auth0 – just links to their broader docs. It feels like we're expected to figure this out ourselves! Should I flag this as a gap?", (PR description for a feature adding new authentication)
This scenario highlights a critical problem: documentation doesn't always bridge the gap between high-level specifications (like 'use OAuth 2.0') and practical implementation details. David is right to feel frustrated – good developer documentation should provide concrete examples and guidance for common integration scenarios, especially when using third-party services like Auth0. Pointing out this lack of specific instructions within the PR description is a valuable contribution to improving the overall quality and usability of the documentation.
20 / 26
Mark: 'I'm reviewing this PR and the `calculate_discount` function uses a constant value for the 'tax rate.' The documentation for the API states that the 'tax_rate' parameter should be dynamically determined based on the user's location. I've flagged it as a potential issue, but the developer says they just thought it was simpler this way. What is Mark's primary concern regarding this situation, and how best to address it within a code review context?
Mark's primary concern is that the developer isn't adhering to documented API specifications. While rapid prototyping can be valuable, consistently deviating from established documentation patterns creates 'documentation debt,' which makes future updates and maintenance significantly more difficult and increases the risk of errors. The correct response involves gently but firmly pointing out the discrepancy and emphasizing the importance of following the defined API contract for consistency and maintainability.
21 / 26
John is reviewing a PR that uses an external library. He notices the documentation for the library's `fetchData` function states: 'This function accepts a single string argument representing the URL to fetch.' However, the code within the PR passes the entire JSON object as a string. John suspects this might be incorrect. Which of the following is his MOST appropriate next step during the code review?
John's primary concern is whether the code is *actually* using the API correctly. Option A is too forceful – developers sometimes have valid reasons for deviating from strict documentation if they understand the underlying functionality. Option C is a reactive approach; John should first try to understand the developer's reasoning. Option B is the most proactive, encouraging the developer to clarify any ambiguities and ensure compatibility with the library's intended usage. Option D is risky – accepting deviations without understanding them could lead to future problems.
22 / 26
During a code review of a new feature for processing user orders, Alice notices the following comment in the `OrderService` class:
"The `validateOrder()` method uses the `CustomerAddressValidator` to check the address. The documentation states 'Ensure all fields are compliant with RFC 5322.' However, the validator only checks for basic format and doesn't perform a full RFC 5322 validation."
This scenario highlights the importance of aligning code with documentation. While the existing validator works, it's not fully compliant as stated. Option 1 is too dismissive; option 3 ignores a critical discrepancy. Option 2 correctly identifies the need for an update and modification, while option 4 proposes a pragmatic approach – updating in future iterations.
23 / 26
Bob sends this Slack message to the team: 'Just found out the API's `getUsers()` endpoint doesn't return user IDs. It only returns usernames! Seriously? The documentation *should* have mentioned this.' What is Bob likely implying?
Bob's frustration stems from a mismatch between expectation and reality. He's not simply criticizing the documentation (option 1); he's expressing a preference for how the data is returned. Option 3 is too strong; option 4 proposes a solution rather than an observation about the existing design.
24 / 26
When writing the PR description for a change that modifies the response format of the `getProductDetails` API endpoint, David includes this sentence: 'The new version returns data in JSON format, as specified by the API documentation.' What is David overlooking?
David's statement is technically correct but incomplete. The documentation likely contains detailed schema information – data types, field names, and potentially examples. Simply stating 'JSON format' lacks the precision needed for effective integration and troubleshooting, which is why this option is correct.
25 / 26
"During my daily stand-up, I mentioned that the API documentation for the 'calculateShippingCost' endpoint doesn't clearly state how it handles shipping rates based on distance. The documentation just says 'Distance influences cost.' What is the most appropriate follow-up action to discuss with the team?
The core issue is a lack of clarity. Option 1 is overly ambitious; option 3 is dismissive and potentially misleading. Option 4 suggests a broader discussion, but requesting an example (option 2) provides the most immediate actionable insight for the team to understand and address the documentation gap.
26 / 26
The backend team receives this API response after a user attempts to log in:
```json
{"status": "error", "code": 400, "message": "Invalid request format. Expected JSON with 'username' and 'password' fields."}
```
What does the error message *primarily* indicate?
While a network issue *could* cause this error code, the message explicitly states that the request format is invalid. The API documentation likely specifies the expected JSON structure with 'username' and 'password' fields. This response highlights the importance of validating input data against documented expectations.
What does the "Developer Documentation Vocabulary — Developer Relations English Exercises" exercise cover?
Practice developer documentation vocabulary: documentation types (reference, guides, tutorials), docs-as-code, documentation debt, progressive disclosure, and API doc anti-patterns.
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 "Developer Documentation Vocabulary — Developer Relations English Exercises"?
This exercise has 26 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.