5 exercises — Practice vocabulary for writing API documentation: reference docs, quickstart guides, concept guides, tutorials, and changelogs.
0 / 10 completed
1 / 10
A technical writer says: "The reference documentation covers all endpoints." A developer asks what distinguishes reference documentation from other doc types. Which explanation is most accurate?
Reference documentation is the "dictionary" of your API — comprehensive, precise, and structured for lookup rather than learning. It is the most commonly visited documentation type by experienced developers integrating your API.
The Diátaxis framework (by Daniele Procida) distinguishes four documentation types: Reference (information-oriented, comprehensive, dry), Tutorial (learning-oriented, step-by-step, narrative), How-to Guide (problem-oriented, task-focused), and Explanation (understanding-oriented, conceptual). Reference docs are the most technically demanding to maintain because they must match the implementation exactly — a single incorrect field name or missing parameter makes the reference unreliable. Best practice: auto-generate reference docs from the API definition (OpenAPI/Swagger for REST, protobuf for gRPC, GraphQL schema for GraphQL) so they stay in sync with code changes automatically.
Key vocabulary:
• reference documentation — comprehensive, structured information about every API element; designed for lookup by experienced users
• OpenAPI (Swagger) — a specification format for documenting REST APIs that enables auto-generated reference docs
• Diátaxis — a documentation framework distinguishing Reference, Tutorial, How-to, and Explanation as four distinct documentation needs
2 / 10
A developer relations manager says: "The quickstart guide onboards users in 10 minutes." What makes a quickstart guide effective?
A great quickstart trades comprehensiveness for speed — its job is to create a "first win" that motivates the developer to invest time in learning the full API, not to document every feature.
The "10-minute quickstart" is a specific design goal used by companies like Stripe, Twilio, and GitHub: if a developer can make their first successful API call in 10 minutes, they are far more likely to continue integrating. Techniques for achieving this: (1) Use copy-pasteable code samples in the developer's language of choice (language selector); (2) Inline configuration — provide a pre-authenticated example so the developer doesn't need to read the auth docs first; (3) Immediate visual feedback — show the API response in the code sample so the developer knows what success looks like; (4) Minimal prerequisites — if you need to create an account, link to it rather than explaining the signup flow inline. The quickstart is the highest-traffic page in most API docs — it deserves the most writing and testing investment.
Key vocabulary:
• quickstart guide — a minimal, fast path to a first successful result; trades comprehensiveness for developer time-to-value
• happy path — the most common, successful use case without edge cases or error handling
• time to first successful call — a UX metric for API documentation measuring how quickly a new developer achieves their first working result
3 / 10
A technical writer says: "The concept guide explains the data model." What is a concept guide's purpose in API documentation?
Concept guides are the most underrated documentation type — developers who understand the underlying model make better decisions, write better code, and require less support than those who only learned from examples.
A concept guide on the data model might explain: "This API uses a resource hierarchy: Organisations contain Projects, Projects contain Deployments. All permissions are scoped to the Project level. If you're used to flat resource models, the hierarchical scoping is the most important thing to understand before integrating." This context prevents a class of errors that would occur if the developer assumed flat scoping. Concept guides are especially valuable for: auth and permissions models (most complex and highest-stakes), data models (entities, relationships, identifiers), async patterns (webhooks, polling, event streams), and rate limiting (quotas, burst limits, backoff strategies). The Diátaxis term for this document type is "Explanation" — its goal is understanding, not task completion.
Key vocabulary:
• concept guide / explanation — documentation that explains the underlying model, architecture, or design decisions to build user understanding
• data model — the entities, relationships, and constraints that define the structure of the API's data
• contextual understanding — the mental model a developer builds of how a system works, which guides their use of reference and tutorial docs
4 / 10
A developer says: "The tutorial has a complete working example." What makes a tutorial different from a quickstart or how-to guide?
Tutorials are the most expensive documentation to write and maintain because they require complete, working, realistic code examples — but they are the most effective at building deep developer competence and confidence with an API.
The Diátaxis distinction between tutorial and how-to guide: a tutorial teaches through a carefully designed learning experience ("follow this to learn X"); a how-to guide solves a specific problem the developer already has ("how do I do X?"). Tutorials are appropriate for: first-time users learning the API's core workflows, complex multi-step scenarios that require understanding before executing, and onboarding to non-obvious patterns (webhooks, pagination, retry logic). A "complete working example" typically means: full authentication setup, all required API calls in the correct sequence, error handling code, and the expected output — everything a developer needs to copy and run the example successfully without filling in missing pieces.
Key vocabulary:
• tutorial — a learning-oriented documentation type; teaches through a structured narrative scenario; explanatory at each step
• complete working example — a code sample covering authentication, the full API interaction, and error handling — runnable without gaps
• how-to guide — a task-oriented documentation type; answers "how do I do X?" for developers who already understand the system
5 / 10
An API team updates its documentation with: "The changelog documents all breaking changes." Why is a changelog especially important for API documentation?
The API changelog is a trust mechanism — it demonstrates that the API team respects the developers who have built on top of their API and will tell them explicitly when something changes that could break their integration.
Best practices for API changelogs: (1) Distinguish breaking vs. non-breaking changes clearly — "Added optional field X" (non-breaking) vs. "Removed field Y" (breaking) vs. "Changed field Z from string to integer" (breaking); (2) Provide migration guides for breaking changes — not just "field Y removed" but "use field W instead, here is how to update your integration"; (3) Provide advance notice for breaking changes (deprecation notices before removal); (4) Date every entry precisely; (5) Link to the relevant documentation for changed behaviour. Semantic versioning (semver) is the standard for communicating break scope: MAJOR version increments always indicate breaking changes, MINOR indicates non-breaking additions, PATCH indicates bug fixes.
Key vocabulary:
• changelog — a chronological record of changes to an API, clearly distinguishing breaking from non-breaking changes
• breaking change — a change that requires existing integrations to be updated to continue working correctly
• deprecation notice — advance warning that a feature will be removed in a future version, giving developers time to migrate
6 / 10
Sarah, a junior developer, comments on a code review: 'This endpoint uses the `get_user_profile` function. Is that documented?' The lead engineer responds: 'Yes, it's in the reference documentation.' What is the primary difference between the reference documentation and other types of API documentation?
The reference documentation specifically details how to use existing functions and endpoints. It contrasts with concept guides which explain the *why* behind an API, and quickstart guides which focus on initial setup. This distinction is crucial for developers seeking immediate implementation guidance.
7 / 10
Mark from Product Management sends a Slack message to the API team: 'We're releasing version 2.0 of the service! The documentation needs to highlight all the new features and changes.' Which document type is MOST suitable for this announcement?
A changelog specifically tracks changes and breaking modifications within an API. This is vital for developers adapting their code to the new version, as it clearly outlines what needs updating and any potential compatibility issues. A concept guide would be too broad for this specific announcement.
8 / 10
During a standup meeting, David from the API team says: 'We're updating the documentation with a new section titled 'Error Codes and Responses.' What is the primary purpose of this type of documentation?
The 'Error Codes and Responses' section details how clients should interpret different responses from the API. This includes understanding status codes (like 404 or 500) and the associated data formats, allowing developers to build robust error handling logic within their applications. It's a critical component of comprehensive API documentation.
9 / 10
Emily is writing a PR description for a new API endpoint: 'This PR introduces the `/users/{user_id}/posts` endpoint. The documentation includes clear examples and usage instructions.' What makes this PR description effective?
A good PR description for an API endpoint should clearly state the new addition and importantly, point to the available documentation. Providing examples and instructions directly within the PR helps developers quickly understand how to integrate the new functionality into their projects, improving collaboration and reducing ambiguity.
10 / 10
The API team is discussing documentation strategies. Alex asks: 'How do we ensure users understand the data models defined in our API?' The team suggests adding a diagram to the documentation. Why would a visual representation of the data model be beneficial?
A visual representation of a data model—typically a diagram—significantly improves comprehension. It allows developers to quickly grasp how different entities relate to each other within the API's structure, leading to more accurate use and reducing potential errors when constructing requests or interpreting responses.
This exercise, "API Documentation Vocabulary", tests your understanding of technical writing vocabulary and phrasing through 10 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 10 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.