Technical Writing and Documentation Questions
The craft of producing durable, reference-quality written artifacts and keeping them accurate: READMEs and quick-start guides, design docs, RFCs and technical proposals, runbooks and deployment guides, model cards, datasheets and data dictionaries, bug reports and reproducible examples, postmortem write-ups, handoff documents, pull request descriptions, code comments, release notes, experiment reports, and knowledge-base articles. Covers structure and information design, writing for a specific audience and for future readers (including plain language and accessibility), templates and style standards, docs-as-code workflows with CI checks, testing of examples and snippets, documentation review and quality checks, versioning and freshness checks on the documents you own, keeping sensitive data out of docs, and measuring whether documentation works. Architecture decision records, API reference docs, PRDs and PR/FAQs, and live presentations are covered elsewhere.
You are writing public-facing release notes for an ML feature that changes what users see. What do you check before publishing, and how do they differ from internal notes?
Sample Answer
Direct answer
Public release notes for an ML feature must be checked for truth, tone, and exposure. Truth: they describe what users will actually see and the limits of it. Tone: they use the user's language, not the team's. Exposure: nothing internal (model names, datasets, unreleased metrics, vendor details) leaks out. Internal notes can be technical and candid, while public notes promise only what you can support.
What I check before publishing
- Matches reality: the feature flag (a switch in the code that turns a feature on or off without redeploying), rollout percentage (the share of users who currently have it), dates and versions in the note equal what is actually live.
- User-visible change, in user terms: what looks different, for whom, and when. If ordering, suggestions or scores can change for the same input, say so.
- Claims are supportable: no "smarter" or "more accurate" unless it was evaluated and you can say on what. Prefer describing behaviour ("suggestions now prefer recent items").
- Limits and failure modes: results can be wrong or vary; say what users should double-check.
- Data and privacy: what data the feature uses, whether customer data trains it, and how to opt out. Privacy or legal review signs off.
- Control and support: where to turn it off, and support has the help article before launch.
- Confidentiality sweep: strip internal model names, experiment IDs, dataset details, unreleased numbers, and anything under a partner agreement.
Public versus internal, for the same change
| Public note | Internal note | |
|---|---|---|
| Audience | Customers | Engineers, support, product |
| Language | Behaviour and benefit | Model, flag, offline evaluation link (results from testing on saved historical data) |
| Limits | Plain caveats | Known regressions (things that got worse), failure modes (the ways it can go wrong) |
| Rollback | Where to switch it off | Flag name, owner, on-call (the engineer currently responsible for responding to problems) |
Redaction example (exposure check)
Before: "Model rank-v3 (experiment EXP-4471) trained on the clicks dataset, with embeddings from a third-party vendor." After: "Search now puts items you opened recently nearer the top." The model name, experiment ID (an internal label for one test run), dataset and vendor all stay internal.
Worked example
Public: "Search now puts items you opened recently nearer the top, so the same query may show a different order than before. Turn this off under Settings, Personalised ranking. Rolling out to all accounts over the next two weeks."
Internal: "A new ranking model replaces the previous one behind the feature flag. Offline evaluation and the A/B result (a comparison of the old and new versions on live users) are linked. Known weaker on rare queries. Rollback: turn the flag off; owner is on-call."
Pitfalls
- Overclaiming ("AI-powered accuracy boost") creates support tickets and trust damage when the feature is wrong once.
- Publishing before rollout finishes makes the note false for part of your users.
How would you tell whether your team's documentation is working? Which signals would you collect, how would you collect them, and which popular measure would you distrust?
Sample Answer
Direct answer
I would judge documentation by what happens after someone reads it: do they find what they need, act on it, and stop asking people? So I collect a few behavioural signals (search that fails, questions that repeat, ramp time for new hires), one or two opinion signals (a page rating and a short survey), and I would distrust raw page views, which go up when docs are good and also when they are confusing.
Signals and how to collect them
| Signal | What it tells you | How to collect |
|---|---|---|
| Search abandonment (searches with no click) divided by all searches | People cannot find the answer | Docs site search logs, weekly |
| "Avoidable ticket" share: support tickets or team-chat questions whose answer was already in the docs, divided by all tickets | Docs exist but are not found or not trusted | Tag tickets at closing; sample if volume is high |
| Time to first successful task for new hires (days to first merged PR, first deploy) | End-to-end usefulness | Onboarding tracker |
| Page feedback ("helpful: yes/no" plus a comment box) | Quality on that page, qualitatively | Widget on each page |
| Freshness: share of tier-1 pages (pages for the most critical services) verified in the last 90 days | Trustworthiness | Metadata "last verified" |
| Time to resolve incidents (MTTR, mean time to resolve) where a runbook (step-by-step procedure for an alert) existed versus not | Link to a real outcome | Incident tool, by tag |
MTTR by runbook tag, with made-up numbers: incidents with a runbook took 45, 30 and 60 minutes (mean 135/3 = 45); incidents without one took 90, 120 and 75 (mean 285/3 = 95). The 50-minute gap is a hint, not proof, since the incident types may differ.
Worked example (illustrative data, run it)
# Tiny, made-up docs-effectiveness data (illustrative). Each row is one week.
weeks = [
# (page_views, searches, searches_with_no_click, tickets, tickets_where_answer_was_in_docs)
(900, 200, 90, 40, 14),
(1500, 210, 60, 33, 9), # after rewriting the top pages
]
for i, (views, searches, no_click, tickets, in_docs) in enumerate(weeks, start=1):
print(f"week {i}: views={views}",
f"| search abandonment={no_click / searches:.0%}",
f"| avoidable tickets={in_docs / tickets:.0%} ({in_docs}/{tickets})")
# Onboarding signal: days from start date to first merged pull request
before = sorted([21, 24, 19, 30, 26])
after = sorted([14, 16, 12, 20, 15])
median = lambda xs: xs[len(xs) // 2]
print("median days to first merged PR:", median(before), "->", median(after))
Output:
week 1: views=900 | search abandonment=45% | avoidable tickets=35% (14/40)
week 2: views=1500 | search abandonment=29% | avoidable tickets=27% (9/33)
median days to first merged PR: 24 -> 15
Reading it: after rewriting the top pages, search abandonment fell from 45% (90 of 200 searches) to 29% (60 of 210), avoidable tickets from 35% (14 of 40) to 27% (9 of 33), and the median time to first merged PR from 24 to 15 days. Note that page views rose too; on their own, views could not have told us whether that was good.
Which popular measure I distrust: page views
Views measure traffic, not usefulness. A confusing page produces repeat visits and more views. A great page that answers in one glance also produces views but no follow-up. Other gameable ones are "number of pages written" and "words". Guard by pairing every activity measure with an outcome measure (views with search abandonment; docs written with avoidable tickets).
Quantitative versus qualitative KPIs (key performance indicators, the few numbers you track to judge success) and the response when one drops
Quantitative: the rates above. Qualitative: free-text feedback, and watching a new hire try a task. When a KPI drops, look at the pages contributing most, read the comments, run a 20-minute test with someone who has not seen the page, then fix and re-measure a few weeks later. Also link the improvement to an outcome such as incident time to resolve: compare incidents where the runbook was used with those where it was not.
Pitfalls
Small samples (say which counts are behind a percentage), changing two things at once, and treating a correlation as proof. Say the numbers back a claim about direction, not exact cause.
Documentation pull requests on your team keep stalling because nobody owns the examples and sample data. What changes to roles, templates and checks would you make?
Sample Answer
Direct answer
Documentation PRs (pull requests, the proposed changes reviewers approve before they merge) stall on examples because an example has three parts, prose, code and sample data, and only the prose has an obvious reviewer. I would fix it with three changes: give each example a named owner (the person who ships the feature owns its example), change the PR template so an example is a required field rather than an afterthought, and add automated checks so a reviewer never has to judge whether an example still works.
1. Roles: who owns what
- Feature author owns the example. Writing the example is part of the definition of done for the feature PR (the checklist that must be satisfied before work counts as finished), not a follow-up ticket. The author knows the real behaviour and the real edge cases.
- Docs owner (a rotating weekly role, not a full-time job) owns unblocking. A rota is a rotating schedule of who takes the duty each week. If a docs PR has had no review for 2 business days, the rota person reviews it or reassigns it. Stalling becomes someone's job.
- Sample-data steward per shared fixture area. A steward is a named person responsible for keeping something in good shape; a fixture is fixed sample data used by examples and tests. Shared sample data (the fake customers and orders used across many pages) lives in one directory, for example
docs/samples/, with a named steward listed in a CODEOWNERS file (a repository file that maps paths to the people or teams whose approval is required).
/docs/samples/ @org/api-team
/docs/guides/ @org/docs-rota
2. Templates: make the gap visible without inviting box-ticking
Add fields, not checkboxes, to the PR template: "Example that demonstrates this change (file path)", "Where the sample data comes from (generated by script, or hand-written and why)", and "Contains no real customer data (yes, and how you know)". A path or a sentence is harder to fake than a tick.
3. Checks: CI (continuous integration, the automatic checks run on every PR) does the judging
- Run every example file, or every fenced code block (a code sample wrapped in triple backticks in Markdown) in the guides, in CI. A broken example fails the PR before a human reads it.
- Generate sample data from a script with a fixed random seed (a fixed starting value so the output is identical every run) instead of editing JSON by hand. CI regenerates it and fails if the committed file differs.
- Validate sample JSON against the API's schema (a machine-readable description of which fields a response must have, and their types), and run a secrets and personal-data scan (a tool that searches files for things like API keys, passwords or real customer emails) over
docs/samples/.
Worked example
A "Add pagination guide" PR sits for three weeks. The reviewer's only comment is "the sample response looks old, who has current data?" Nobody answers because nobody owns it. After the changes: the author of the pagination feature had to attach the example path in the PR, the sample response is produced by make samples (a command that runs the seeded generator script and rewrites the sample files) from the seeded generator, CI validates it against the schema, and the rota person merged it on day 2. The reviewer only had to read the prose.
Trade-offs and pitfalls
- Every extra check slows contributors. Start with the two or three most-used examples and widen only when failures show up.
- Ownership by the feature author fails for cross-team examples. Give those a steward in CODEOWNERS, otherwise you recreate the orphan.
- Do not let the docs owner become the person who writes everyone's examples. That moves the bottleneck instead of removing it.
- What would change my call: on a team of three, skip the rota and just make the feature author and one named reviewer responsible. Measure success by median PR age (the middle value of the ages when sorted: if five docs PRs were open 3, 9, 14, 21 and 30 days the median is 14; after the change, 1, 2, 3, 4 and 20 days gives a median of 3, and the one slow outlier does not hide the improvement) and by how often an example breaks after merge, not by how many boxes were ticked.
Your product ships a new release every quarter. How do you version and migrate your documentation, including guides and how-to pages, so readers on old releases are not misled?
Sample Answer
Direct answer
Treat each supported release as a frozen snapshot of the docs, keep one moving "latest" copy, and make every page announce which version it describes. Readers on old releases land on the docs that match what they run, and anything they might mistake for current carries a clear banner and points to the newer page. Version the reference and how-to pages by release, and keep conceptual overviews shared unless they truly diverge.
Structure
- Docs live in the same repository as the code (docs-as-code, meaning documentation stored and built like source code). Each release branch or tag has its own docs, so a doc fix can be back-ported (copied onto older supported versions) with the code fix. A release branch is a long-lived branch holding one released version so it can still get fixes; a tag is a permanent label on one commit.
- Publish a version selector and stable URLs. For example
/docs/latest/,/docs/3.2/,/docs/3.1/. Tools built for this include Docusaurus (itsdocs:versioncommand snapshots the current docs), mike for MkDocs (mike deploypublishes a version; MkDocs is a static site generator that turns Markdown into a website), and Read the Docs (a hosted service that builds docs from your branches and tags). The tool matters less than the rule. If you have no tool yet, Docusaurus is an easy start because versioning is built in; use mike if you already run MkDocs; Read the Docs suits open-source projects that want hosted builds. - Banners on old versions: "You are reading docs for 3.1. The latest version is 3.2." linking to the equivalent page if one exists.
- Search-engine hygiene. Point old versions' canonical link (the tag telling search engines which URL is the preferred copy) at the latest page, or mark them noindex (an instruction telling search engines not to list the page), so a search does not land people on outdated instructions.
- Support policy tied to docs. Fix errors in supported versions (say, the last two releases). Older versions are frozen, labelled archived, and not edited.
- Migration path. Each release ships an upgrade guide (what changed, what breaks, how to migrate) and a changelog (the dated list of changes per release). Pages whose behaviour changed link to it.
Which content gets versioned
| Content | Versioned per release? | Reason |
|---|---|---|
| API and CLI reference | Yes, generated from that release's code | Exactness matters |
| How-to guides that use specific features | Yes | Steps and screenshots change |
| Concepts and architecture overviews | Shared, with "since 3.0" notes | Rarely diverge |
| Tutorials | Latest only, tested each release | Cost of maintaining many |
Worked example
Release 3.2 renames the setting max_conn to pool_size. In the 3.2 docs the reference page documents pool_size, and the how-to says "Set pool_size". The 3.1 snapshot still says max_conn, with the banner. The upgrade guide has an entry: "3.2: max_conn is renamed pool_size; the old name works until 4.0 and logs a warning." A reader on 3.1 googles max_conn, arrives at the 3.1 page, sees the banner, and finds the migration note one click away. Without versioning, they would see 3.2 text and set a name their release ignores.
Trade-offs and pitfalls
- Copying the whole docs tree per release is simple but multiplies review work. Mitigate with a check that a fix to latest raises a "back-port?" prompt for supported versions.
- Conditional text ("in 3.1 only") on one page avoids duplication for small differences but gets unreadable past two or three variants. Snapshot when differences pile up.
- Broken links between versions are common; run a link checker (a tool that follows every link and reports ones that lead nowhere) per version in CI.
- What would change my call: for a hosted service with one live version, version only the API (by API version) and keep a dated changelog instead of full snapshots.
Write a one-page quick-start for engineers adopting a new internal shared component, for instance a feature store. What must a first-time user be able to do in ten minutes, and which pitfalls belong on the page?
Sample Answer
Direct answer
The quick-start's job is one measurable outcome: a first-time user gets real value from the component in ten minutes, without asking anyone. For a feature store (a shared system that keeps precomputed model input values, called features, so training and live serving use the same definitions), that means install, authenticate, read one existing feature, and see it verified. An entity is the thing the features describe (here a customer, identified by an entity id such as customer_id = 1042). Online features are the latest values served quickly for live predictions, as opposed to offline features, which are historical values used to build training data. A namespace is a named folder that keeps sandbox features apart from production ones, and the catalogue is the searchable list of registered features and their owners. The pitfalls on the page are the ones that bite first-time users, not a full reference.
What a first-time user must do in ten minutes
| Minutes | Step | Success check |
|---|---|---|
| 0-2 | Install the client with a pinned version and set the project name | featurestore --version prints a version |
| 2-4 | Authenticate with your own team credentials (never a shared production key) | A test call returns "authenticated as <you>" |
| 4-6 | Read features for one known entity id (for example customer_id = 1042) | You see the feature values and a timestamp |
| 6-9 | Define one new feature in a sandbox namespace and fetch it | The new value appears in the read |
| 9-10 | Find your feature in the catalogue or UI and see who owns it | You can name its owner and freshness |
The steps use an illustrative client, since this is an internal component:
from featurestore import Client # illustrative internal client
client = Client(project="sandbox")
row = client.get_online_features(
features=["customer.orders_30d", "customer.avg_basket"],
entity={"customer_id": 1042},
)
print(row) # expect two values plus the time each was computed
The page states the expected result after each step, so success is visible without guessing. In the code: Client(project="sandbox") connects to the sandbox namespace, get_online_features asks for two named features for one customer, and the print should show one value per feature plus the time each was computed.
Pitfalls that belong on the page
Pitfalls 1 and 2 are the ones that fail silently and cost the most; 3 to 6 are housekeeping the page can state in one line each.
- Point-in-time correctness. When building training data, fetch each feature value as it was at the label's timestamp. Using today's value leaks the future into training, so the model looks better offline than it will in production. Example (illustrative): customer 1042 churned (stopped buying) on 2025-03-15, and the label timestamp is that date. Their
orders_30dwas 5 on 2025-03-15, but by today (2025-06-01) it is 0 because they left. If training uses today's 0, the model learns "zero orders means churn", which looks perfect offline, yet in production the model only ever sees the value 5 before the customer leaves. The correct training value is the one as of 2025-03-15. - Training-serving skew. Reuse the registered definition. Recomputing the feature separately in your own code is how the two sides drift apart.
- Freshness. A feature has a refresh interval and a time-to-live (how long a value stays valid). Say which features are hourly and which daily, so a user does not expect real-time.
- Entity keys. Use the documented key name and type (an id stored as text vs integer silently returns nothing).
- Sandbox vs production. Where to experiment and what needs a review before promotion.
- Cost and quotas. Large backfills (recomputing history) consume shared capacity: ask the owner first.
Worked example
A new engineer reads the page at 10:00. By 10:04 they are authenticated. At 10:06 they see orders_30d = 7 for customer 1042 with a computed-at time. They ask, "is this current?" The page's freshness note says daily at 03:00, so a 10:00 read is 7 hours old, which they can decide is acceptable for their model. They never opened the full reference.
Trade-offs and pitfalls of the page itself
- The page must stay one screen long. Link to the reference, the on-call channel, and the design doc rather than embedding them.
- Test the ten-minute claim by watching someone new do it, then cut every step where they hesitated.
- Put the sharpest pitfall (point-in-time leakage) near the top of the pitfalls list, since it is silent and costly.
- Examples must use the sandbox, so copy-paste never touches production.
Unlock Full Question Bank
Get access to all 19 Technical Writing and Documentation interview questions and detailed answers.
Sign in to ContinueJoin thousands of developers preparing for their dream job.