Your team single-sources one DITA task topic into both a web help portal and a printed PDF. The web output needs an interactive 'Try it' callout with a live API console; the PDF must show a static screenshot instead. What is the cleanest single-sourcing approach that avoids forking the topic?
- A. Duplicate the topic into two variants and manually keep them in sync each release
- B. Use conditional processing (filtering/flagging via ditaval) on a shared element, keying the console and screenshot to output-specific profiling attributes ✓
- C. Move the console and screenshot into the DITA map so the topic stays identical for both outputs
- D. Convert the topic to Markdown so each static site generator can inject its own widget
Correct answer: B. Profiling attributes resolved by a ditaval at build time let one source topic render output-specific content without forking, which is the core mechanism of DITA single-sourcing.
An SME is unresponsive and the product is still changing. You must document a new POST endpoint that returns 201 on success. Reading the code, you find the handler returns 200 with the created resource body. Which action best balances accuracy and risk?
- A. Document 201 because REST convention says resource creation should return 201 Created
- B. Document 200 as observed, but flag the discrepancy to engineering as a likely defect before publishing anything definitive ✓
- C. Omit the status code entirely until the SME confirms
- D. Document both 200 and 201 as acceptable so the reader is covered either way
Correct answer: B. Docs must describe actual behavior, not idealized convention, but a convention-violating status code is worth surfacing as a possible bug rather than silently enshrining it.
Leadership asks you to prove documentation ROI. Support-ticket volume for a feature dropped 30% the same month you shipped new docs, but a UI redesign also shipped that month. What is the most defensible way to attribute value to the docs?
- A. Claim the full 30% ticket reduction as documentation deflection
- B. Correlate in-doc search-to-resolution and 'was this helpful' signals plus ticket-topic tagging for doc-addressable issues, isolating the doc-attributable slice ✓
- C. Report page views and time-on-page as the ROI metric
- D. Decline to measure because doc value is inherently subjective
Correct answer: B. Isolating doc-attributable deflection via topic-tagged tickets and in-doc resolution signals avoids the confound of the simultaneous UI change and gives a defensible attribution.
You are structuring docs so a RAG system and autonomous agents retrieve them accurately. A long troubleshooting page mixes ten unrelated errors under generic headings. What restructuring most improves retrieval precision?
- A. Add more synonyms and keywords throughout the existing page to raise its embedding similarity
- B. Split into self-contained chunks, each with a specific descriptive heading, the error signature, and a complete standalone answer ✓
- C. Increase the page length so more context is available in a single retrieved document
- D. Move the page higher in the site navigation so crawlers index it first
Correct answer: B. Retrieval quality depends on semantically focused, self-contained chunks that answer one question without external context, not on keyword stuffing or longer monolithic pages.
You must deprecate a v1 API endpoint that thousands of integrations still call. Which change-management documentation strategy minimizes breakage while signaling the sunset?
- A. Immediately delete the v1 reference page and redirect it to the v2 page
- B. Keep v1 docs live with a prominent deprecation notice, the sunset date, the specific replacement mapping, and a migration guide, while continuing to version v1 alongside v2 ✓
- C. Add a single banner to the homepage announcing v1 is deprecated
- D. Update the v1 examples in place to call v2 so readers copy the new calls
Correct answer: B. Responsible deprecation keeps the old reference discoverable with a dated notice, an explicit v1-to-v2 mapping, and a migration path so existing integrators can transition without silent breakage.
Engineering wants exhaustive parameter-level depth on a quickstart; UX wants a 5-minute happy path with almost no options. Both escalate to you. What resolution best serves the actual user goal of a quickstart?
- A. Average the two demands into a medium-length page with some parameters and some narrative
- B. Keep the quickstart minimal to first success and use progressive disclosure to link out to the full reference for depth ✓
- C. Side with engineering because technical accuracy outranks simplicity
- D. Side with UX and delete the reference material to keep everything short
Correct answer: B. A quickstart's job is fastest time-to-first-success; progressive disclosure satisfies both stakeholders by layering depth behind links rather than compromising the quickstart itself.
You are migrating 4,000 legacy doc URLs to a new static-site structure with different paths. SEO ranking and existing bookmarks must survive. What is the essential technical step?
- A. Publish the new URLs and submit a fresh sitemap so search engines re-crawl
- B. Implement 301 redirects mapping each old URL to its new equivalent, then update the sitemap and internal links ✓
- C. Use 302 redirects so you can revert quickly if rankings drop
- D. Add canonical tags on the new pages pointing to themselves
Correct answer: B. 301 (permanent) redirects pass link equity and preserve bookmarks/rankings during a URL restructure; 302 is temporary and does not reliably transfer ranking signals.
In your OpenAPI spec, a request body field 'email' is required, format email, but the backend also silently accepts null and treats it as an opt-out. How should the reference documentation handle this mismatch?
- A. Document only what the spec says, since the spec is the contract
- B. Reconcile with engineering: either the spec should mark it nullable/optional with documented opt-out semantics, or the backend should reject null; document the agreed behavior, not the current contradiction ✓
- C. Add a prose note that null 'sometimes works' so readers are aware
- D. Mark the field optional in the docs to match observed behavior and leave the spec unchanged
Correct answer: B. An accurate reference requires resolving the spec-versus-behavior contradiction at its source so the documented contract matches reality, rather than papering over it with hedging prose or a silent doc-only edit.
You document an OAuth 2.0 authorization-code flow with cURL examples. A reviewer notes your example puts the client_secret in the authorization request URL. Why is this a correctness problem, not just style?
- A. URLs have a length limit that the secret could exceed
- B. The client_secret belongs in the server-side token-exchange request, not the front-channel authorization request, where it would be exposed in browser history, logs, and referrers ✓
- C. cURL cannot send query parameters and a JSON body simultaneously
- D. The authorization endpoint only accepts POST, so a URL parameter fails
Correct answer: B. In authorization-code flow the secret is used only in the back-channel token exchange; placing it in the front-channel authorization URL leaks it through logs, history, and referer headers.
You have three days and a backlog of 20 doc issues. Two are typo fixes, one is a missing authentication section on the most-visited API page, five are new-feature topics for a feature launching next quarter, and the rest are minor clarifications. What triage ordering is soundest?
- A. Do the two typos and many minor clarifications first to clear the most tickets
- B. Prioritize the missing authentication section on the high-traffic page first, as it is high user-impact and blocking, then triage the rest by impact ✓
- C. Start the five next-quarter feature topics now to get ahead of the launch
- D. Work strictly in the order the issues were filed to be fair
Correct answer: B. Risk- and impact-based triage puts the high-traffic, currently-blocking authentication gap first; next-quarter topics are not yet time-critical and ticket-count optimization ignores user impact.