5 exercises — Practice vocabulary for testing documentation quality: running code samples in CI, broken link checking, auto-generated screenshots, readability testing, and zero 404s.
0 / 12 completed
1 / 12
A technical writer says: "We run code samples in CI to catch outdated docs." A developer asks how this works. Which explanation is correct?
Running docs code samples in CI is the highest-leverage practice for keeping documentation accurate — it converts documentation maintenance from a human memory task to an automated quality gate.
Implementation approaches: (1) Doctest (Python) — executable examples embedded in docstrings, run by pytest; (2) mdBook / runbook tools — markdown code blocks marked as "runnable" are extracted and executed; (3) Custom test harnesses — scripts that extract code blocks from markdown by language/tag and execute them against a test API environment; (4) Jupyter notebooks — entire documentation notebooks executed as part of CI. The key insight: outdated code samples are the most-complained-about documentation problem because they directly waste developer time. If the first code sample a developer tries doesn't work, trust in the documentation collapses. Automation converts this from "we try to remember to update docs when the API changes" to "the build fails if docs aren't updated."
Key vocabulary:
• docs-as-code — treating documentation with the same tooling and practices as software code (version control, CI, tests, code review)
• runnable code sample — a documentation code example that is also executed as part of CI to verify its correctness
• documentation CI pipeline — automated checks (link checking, code execution, spell checking) run on documentation changes
2 / 12
A docs team says: "The broken link checker runs on every build." Why is automated link checking important for documentation?
A broken link is documentation's equivalent of a 404 in production — it breaks the user's flow and signals that the documentation is not actively maintained, eroding trust in the accuracy of everything else.
Link checking tools: htmltest (Go, fast), lychee (Rust, supports parallel checking), Broken Link Checker (Node.js), GitHub Actions has built-in link checking. Best practice: run on every PR for fast feedback, and also on a daily schedule to catch externally-broken links that aren't caused by your own changes. Configuration considerations: exclude known external sites that block crawlers (some documentation sites return 403 to bots), configure appropriate timeout thresholds, and distinguish errors (true broken links) from warnings (redirect chains, slow responses). The "zero 404s" target mentioned in the exercise question is a maintainability standard — it means the team has committed to treating broken links as build failures, not just warnings.
Key vocabulary:
• broken link checker — an automated tool that verifies all hyperlinks in a documentation site return valid responses
• 404 error — an HTTP response indicating a requested page does not exist; in docs, signals unmaintained or relocated content
• anchor link — a link to a specific section within a page (using a # fragment); breaks when the section heading changes
3 / 12
A technical writer explains: "The screenshot is auto-generated from the UI." Why would a team choose to auto-generate screenshots rather than capture them manually?
Auto-generating screenshots converts documentation image maintenance from a human-memory task to an automated process — every UI change that breaks a screenshot is either fixed automatically or surfaced as a CI failure.
Implementation approaches: (1) Playwright/Puppeteer scripts that navigate to specific UI states and capture screenshots — run in CI on each UI deployment; (2) Percy or Chromatic visual testing — captures screenshots and diffs against baselines, highlighting changes; (3) Storybook documentation — component screenshots auto-generated from the component library. The most sophisticated implementations parameterise screenshots: the same script captures the same UI state across multiple locales, screen sizes, and themes — generating the full matrix of documentation images automatically. The key technical challenge is making the UI state reproducible: the script must log in, navigate to the correct state, populate the correct data, and capture consistently.
Key vocabulary:
• auto-generated screenshot — a documentation image captured programmatically by a script rather than manually by a human
• visual testing — automated comparison of UI screenshots against approved baselines to detect unintended visual changes
• UI state reproducibility — the ability to consistently navigate a UI to a specific state for automated screenshot capture
4 / 12
A documentation quality initiative includes: "The docs pass the readability score test." What does readability testing measure and why does it matter for technical documentation?
Readability testing gives technical writers objective feedback on prose clarity — it is not about dumbing down technical content but about expressing technical ideas in the clearest, most efficient language possible.
The Hemingway Editor is popular for technical writing review: it highlights passive voice (often clearer as active), adverbs that can be cut, complex words with simpler alternatives, and sentences that are "hard to read" or "very hard to read." Google's developer documentation style guide specifically advises: use active voice, use second person ("you"), write short sentences, and avoid unnecessary hedging words. Readability targets for developer documentation typically allow somewhat lower scores than consumer content — technical precision sometimes requires longer sentences. But consistently "very hard to read" passages in procedural documentation indicate a writing quality problem that will cause developers to abandon the docs and resort to trial and error.
Key vocabulary:
• readability score — a metric quantifying how easy prose is to understand, based on sentence and word length measures
• Flesch-Kincaid grade level — a readability formula that estimates the US school grade level needed to understand the text
• active voice — sentence construction where the subject performs the action ("click the button") rather than passive ("the button should be clicked")
5 / 12
A docs team reports: "The doc site has zero 404s." A new team member asks what achieving "zero 404s" requires as an ongoing practice. Which answer is most complete?
Zero 404s is a documentation quality commitment, not a one-time achievement — it requires automated monitoring, a redirect strategy for moved content, and a team culture where broken links are treated as build failures.
The redirect strategy is the most important element for established documentation sites: when a page is renamed or restructured, the old URL must redirect to the new location. Without this, every external link and search engine bookmark pointing to the old URL becomes a 404. Most documentation frameworks support redirects in configuration (Docusaurus, MkDocs, Hugo, Jekyll all have redirect plugins). A stable URL structure policy — agreed patterns for how pages are named that don't need to change — reduces the volume of redirects needed. For very large documentation sites, a "404 monitoring" pipeline that checks the site map against a crawl-based link inventory helps catch gaps that CI doesn't cover (e.g., links in content templates or dynamically generated pages).
Key vocabulary:
• redirect — an HTTP response that sends the browser from an old URL to a new location; preserves incoming links when content moves
• stable URL structure — a documentation URL naming convention designed to not require changes, reducing redirect maintenance
• sitemap — an index of all pages in a documentation site, used by search engines and link checkers to discover all URLs
6 / 12
Liam, a junior developer, comments on a PR: 'This function doesn't document the return value. It should clearly state what type it returns and under what conditions.' What does Liam likely mean by 'documenting the return value'?
Liam is referring to the specific details of the return value – its type and the different scenarios it might produce. Documentation should provide precise information about a function's output, not just a general description of what it *does*. Options A and D are too broad; B is an incorrect use of 'documentation'.
7 / 12
Sarah, the documentation manager, sends a Slack message to the team: 'We're using Doxygen to automatically generate API reference documentation. We've configured it to scan all our C++ code.' What is the primary benefit of using automated tools like Doxygen for generating documentation?
Automated tools like Doxygen reduce the risk of inconsistencies and manual errors. By scanning the source code, the tool can generate API reference documentation automatically, which significantly speeds up the process compared to manually creating and maintaining documentation. Option A is incorrect as automated tools aren't perfect; option C is a side effect, not the primary benefit, and D describes translation software.
8 / 12
Maya, a senior developer, is reviewing a PR for a new authentication service. She comments: 'The API response format isn't clearly documented. We should include an example JSON payload showing the expected structure and data types.' What aspect of documentation is Maya primarily concerned about?
Maya is focusing on providing developers with practical guidance. She wants a clear example of the data format to ensure correct usage and integration. Incorrect options highlight other important documentation aspects (endpoint definitions, security protocols, or rate limits) but don't address her specific concern about API response structures.
9 / 12
During a standup meeting, David asks the documentation team: 'We're using Markdown to write our guides. Is that the best choice for technical documentation?' What is the most appropriate response?
David's question highlights the trade-offs between simplicity and features. While Markdown is suitable for smaller guides, larger technical documentation projects benefit from tools that offer more robust capabilities such as cross-referencing and table of contents generation – crucial for maintainability.
10 / 12
Chloe, a developer, is creating a PR description for a new feature. She writes: 'This code implements the calculate_average function, which takes an array of integers and returns the average value.' What technique is Chloe employing to improve documentation clarity?
Chloe's description is focusing on providing clear information about the function's behavior. Specifically, detailing the inputs and outputs – parameter types and return values – is fundamental to understanding how a function works. This avoids ambiguity for other developers.
11 / 12
The documentation team discovers that many users are struggling to understand the output of the get_user_profile API. They decide to add a detailed explanation of the response format. What is the primary goal of this action?
The core purpose is user experience. Providing a clear explanation of the response format directly addresses usability challenges and helps users effectively utilize the API. Addressing user needs improves adoption and reduces frustration.
12 / 12
During a code review, Alex comments: 'The documentation for this class isn't comprehensive enough. We need to explain the purpose of each method and its potential side effects.' What type of documentation is Alex primarily suggesting should be added?
Alex is advocating for *usage documentation*, which focuses on explaining *how* to effectively utilize a component. This includes detailing method purposes and potential side effects – crucial information for developers integrating the class into their projects.
This exercise, "Documentation Testing Vocabulary", tests your understanding of technical writing vocabulary and phrasing through 12 multiple-choice questions drawn from real workplace scenarios.
Is this exercise free to use?
Yes. Every exercise on CoderSlingo, including this one, is completely free — no account, sign-up, or payment required.
How many questions does this exercise have?
This exercise has 12 questions. Each one presents a realistic sentence or scenario with multiple-choice options and an explanation once you answer.
What happens after I answer a question?
You'll see immediate feedback showing whether your answer was correct, along with a short explanation of why — then a button to move to the next question.
Can I retry the exercise if I get questions wrong?
Yes. Once you reach the results screen, click "Try again" to reset your answers and go through the exercise from the start as many times as you like.
Do I need to create an account to take this exercise?
No account is needed. Your answers are scored in your browser during the session — nothing is saved to a server, so you can jump straight in.
Is my progress saved if I leave the page?
No — progress within an exercise resets if you navigate away or reload. Each exercise is short enough to complete in a few minutes in one sitting.
Who is this Technical Writing exercise for?
It's designed for IT professionals and learners who want to sound natural discussing technical writing topics in English — useful for meetings, documentation, interviews, and day-to-day communication with English-speaking teams.
How is this different from reading a glossary or blog article?
Exercises like this one are active recall drills — you have to choose the correct term or phrasing yourself, which builds retention faster than passively reading a definition.
Where can I find more Technical Writing exercises?
Browse the full Technical Writing exercises hub for more practice, or explore other exercise categories covering vocabulary, grammar, interviews, and workplace communication.