Lesson 4 of 4 · 60 min
Keep the example correct after the launch
Create a maintenance record for a demo and its documentation.
Technical content decays when the product, dependency, or environment changes. A tutorial that worked at launch can later fail at installation, authentication, or output validation. Treat maintenance as part of authoring. A useful artifact names its owner, tested versions, expected outputs, and the changes that require another check.
Make the example's executable path small and inspectable. A separate source file can generate a displayed snippet in a real documentation system, reducing drift between the page and the working example. In this Markdown planning draft, the important design is to identify one owning example and a verification procedure rather than maintaining unrelated copies.
Define a freshness signal that means something. A page's last-edited date can change because of a spelling fix. A tested-on date should record the runtime, dependency versions, fixture, and result. If a linked service changes its API, the owner should know which examples depend on it. A broken link check is useful, but a live URL does not prove the instructions are correct.
Retire or label unsupported paths clearly. Do not silently redirect a tutorial for an old API to a new page whose steps differ. A learner following the old sequence needs a migration note or an explicit supported-version statement. Preserve the reason for a change so support and community contributors can understand older reports.
Worked example
A fictional event tutorial has this maintenance record:
code
1owner: developer-education2tested runtime: Python 3, version recorded at release check3fixture: E1=10, repeated E1=10, E2=54expected output: 155behavior boundary: single process, memory only6recheck triggers: runtime support change, event schema change7fallback: printed trace with the same fixtureA new event schema renames amount to value. The owner updates the example and explanatory text together, checks the output, and adds a note for readers using the older schema. The change is not complete if only the screenshot shows the new output while the copyable code still reads amount.
Treat the example as an owned dependency
A maintained example has a small dependency map. It depends on a runtime, libraries, an API or fixture schema, copyable instructions, and an expected result. A change to any one can invalidate the learning path even when the others remain available.
| Dependency | Owning source | Recheck trigger |
|---|---|---|
| Runtime | Supported-version record | Support range or syntax changes |
| Event fields | Product schema/reference | Field rename, type, or semantics change |
| Copyable sample | One owning code example | Logic or dependency update |
| Tutorial text | Page linked to sample version | Changed command or explanation |
| Expected result | Fixture manifest | Changed input or behavior contract |
| Fallback | Trace generated from same fixture | Any mechanism or output change |
The map does not require building a complex documentation platform. Even a small Markdown record can prevent ownership gaps. One person or team should be accountable for the learning path, with reviewers for technical behavior outside their authority.
Record verification separately from editing
code
1Content revision:R42Editorial edit date:2026-09-223Behavior check date:record actual completed check, not assumed4Runtime:exact version used in that check5Sample revision:matching source identifier6Fixture:declared three-event input7Expected:158Observed:record only after actual run/trace9Coverage:local mechanism; live provider auth unverifiedThis template deliberately leaves the observed field conditional. Do not fill it with an expected result and label it observed without performing the check. A spelling edit can update the content revision without refreshing the behavioral verification date.
A trace review and an execution check are both useful but different. Tracing can verify simple control flow and expected arithmetic. Running can expose environment or dependency problems. Neither alone proves an external provider's current authentication, rate limits, or permissions if the sample uses a local fixture.
Update a schema change coherently
When amount becomes value, identify whether this is a rename with the same numeric meaning or a semantic change too. If units change from major to minor currency units, replacing a key name is insufficient. The fixture, calculation, expected output, and explanation need a revised contract.
For a pure field rename, update the owning sample, all copyable snippets, diagnostic examples, reference links, and expected-output check. A screenshot can be regenerated last, after the behavior is verified. Do not use the screenshot as the only source of truth for code a learner will copy.
Preserve a supported-version note for old readers. If the old API is still supported, explain which sample revision matches it. If support ended, provide a clear migration route and state what changed. A silent redirect to different instructions can make an old bug report impossible to interpret.
Define a maintenance response
A report of a removed import should trigger a reproduction against the declared version. If the instructions allow a newer dependency whose API removed the function, either narrow the supported version or update the example after checking the replacement. Avoid simply pinning an obsolete version indefinitely without considering support and security constraints.
A link checker only tests availability of a target under its own request conditions. It cannot establish that the tutorial's commands work or that the page still describes the same contract. Keep link, syntax, execution, and semantic checks separate in the maintenance record.
A scheduled review can help, but event-driven triggers are also necessary. Product teams should notify the accountable owner when a relevant schema or API changes. Community reports can catch gaps, but relying entirely on strangers leaves the user-facing promise unowned.
Misconceptions and a second exercise
One misconception is that a recent last-edited date proves the code was retested. It may reflect punctuation. Another is that updating the sample alone updates every published copy. Duplicated snippets, slides, and recordings can drift unless their relationship is tracked.
Exercise: source code reads value and returns 15; the tutorial still copies amount; the screenshot shows 15; the dependency link resolves. Is the learning path ready? No. The copyable path is inconsistent even though individual artifacts look plausible. Update the tutorial and version note, then verify the actual sequence a new learner follows. Award one point for identifying the copy path, one for coordinating revisions, one for the end-to-end check, and one for preserving truthful verification metadata.
The finished maintenance artifact should answer who owns the example, what version is supported, when its behavior was actually checked, and what change requires another check. That makes a demo a reliable learning resource after the launch session ends.
Exercise and solution
A link checker passes, but three learners report that the example imports a removed function. What should the maintenance process check? Run or trace the declared sample against the stated dependency version, confirm the replacement API, and update the source and instructions together. Award one point for behavior verification, one for version specificity, and one for synchronizing the artifacts. A passing link check cannot establish API compatibility.
Interview probe and wrap-up
Who should own an example that spans two teams? A strong answer names one accountable owner and explicit reviewers for product-specific behavior, with a route for change notifications. Follow up with an abandoned repository. A weak answer assumes public contributions will eventually fix it. A maintained tutorial is a supported learning path with a clear owner and a result that someone can still verify.
Sources
docsGoogle code-sample style guidancedevelopers.google.comdocsGitHub open-source contribution guideopensource.guidedocsGoogle technical writing: audience and documentsdevelopers.google.comCheckpoint
A spelling fix changes last-edited date. What does it prove about execution?
AThe sample was run on current dependencies.BThe provider integration was verified.CNothing new unless a behavior check was actually performed and recorded.DEvery old report is obsolete.
Sign up free to answer and see whyCheckpoint
A response field changes from amount in major units to value in minor units. Which maintenance step protects the taught result?
ARename the field and keep the old expected numeric result because the logical concept is still money.BUpdate the displayed snippet but leave the downloadable fixture on the prior unit contract.CKeep the old calculation and divide only the final screenshot value to match the new UI.DReview the conversion, fixtures, calculation, expected result, and all learner instructions together.
Sign up free to answer and see whyCheckpoint
A link checker passes while an imported function was removed. What is established?
AThe sample is compatible.BThe URL resolves under the checker; behavior needs a separate check.CThe runtime version is correct.DThe output matches the fixture.
Sign up free to answer and see whyCheckpoint
A tutorial depends on an SDK team and an API team. Which ownership contract makes a reported learner failure actionable?
AName one accountable example owner, each dependency's technical reviewer, and change-notification and escalation routes.BAssign ownership to whichever team receives the first ticket, without a fallback when the cause crosses both.CAsk each team to verify only its component and treat the combined tutorial as correct when both components pass separately.DKeep the original author's name as owner even after their access and maintenance responsibility end.
Sign up free to answer and see whyCheckpoint
The repository example is updated, the copied tutorial still uses the old API, and its screenshot shows the new result. What release check is needed?
APublish both versions without labels and let the installed dependency choose which instructions apply.BApprove the page because the screenshot matches the new result.CApprove the page because the repository example passes, then leave copyable commands for a later revision.DAlign and verify the learner's copyable sequence, supported versions, and expected result across both artifacts.
Sign up free to answer and see whyCan you distinguish editorial freshness from verified behavior and update every dependent teaching artifact when a contract changes? State the relevant identifiers, failure boundary, and evidence in your own words before selecting your confidence.
Not yetGetting thereConfident
Sources
Free to read · better with Enzo
Learn it with Enzo
Save your progress, answer the checkpoints, and let Enzo quiz you on what you just read.