Lesson 3 of 4 · 60 min

Document the failure a learner will actually see

Write a diagnostic path that separates setup, permission, and input problems.

A tutorial's failure path is part of the lesson. Developers often learn a tool by correcting an error, and the error needs to reveal enough information to choose a next action. A page that shows only the perfect output leaves learners guessing when their environment differs from the author's.

Begin with the observable symptom. A command not found error points toward installation or path setup. A connection refused error indicates that the expected local endpoint is not accepting the connection. A 401 response concerns authentication, while a documented 429 response concerns request rate and may include retry timing. These are different branches, so do not recommend reinstalling the whole project for each one.

A good diagnostic step changes one variable or gathers one discriminating observation. Verify runtime version before changing code. Check the configured endpoint before rotating credentials. Read the response status before parsing the body as the expected success shape. Preserve the user's state where possible. A blanket cleanup command can erase the evidence or destroy unrelated files.

Keep instructions safe to copy. Use a dedicated demo directory, explicit placeholder names, and commands that target only that directory. If a step changes an account or creates a billable resource, disclose the action and provide an appropriate cleanup path. A local tutorial can often avoid that requirement entirely.

Worked example

A fictional workshop uses a local endpoint at localhost port 8080. A learner reports connection refused. The diagnostic card asks whether the local server process is running and whether the printed port matches 8080. The learner finds that the server started at 8081. They update the client endpoint or restart the server with the documented port. No credentials are involved in this failure.

A second learner receives 401 from a real sandbox API. The card instead checks whether the placeholder token was replaced and whether the token belongs to the intended sandbox. It tells the learner to avoid pasting the token into a public chat. The same visible word failed does not justify the same repair.

Build a diagnostic decision tree

A useful troubleshooting page starts from an observation the learner can verify. It should not ask them to choose a root cause before gathering evidence. Separate environment, transport, HTTP response, and application contract.

code

1Did the command start?2  no -> runtime/path/file-location check3Did a connection reach the intended endpoint?4  no -> process, host, port, network route5Did an HTTP response arrive?6  yes -> status and content-type before success parsing7Does the response match the documented success contract?8  no -> endpoint/auth/input/rate branch using observed evidence

The tree is a guide, not a theorem that one status has only one possible cause. A proxy can return an HTML error page before the application runs. A 401 can reflect an expired token, missing token, or wrong environment under the service's contract. A 403 often indicates denied access, but the exact disclosure policy must be read rather than guessed.

Inspect a concrete response artifact

Observation	What is established	Useful next check
Connection refused at localhost 8080	No listener accepted that connection	Server process and printed port
HTTP 404, text/html	A response arrived, but not expected JSON success	Actual URL, route, proxy/error body
HTTP 401	Authentication was not accepted under this API	Token presence, environment, expiry guidance
HTTP 429 with Retry-After	Rate limit response with retry guidance	Documented delay and bounded retry policy

A JSON parse error after 404 HTML is a symptom of applying the wrong parser expectation. Changing the success schema will not turn an HTML error page into a successful API result. Inspect the status and safe response metadata, then find why the wrong route or error path was reached.

A small teaching pseudocode sequence illustrates the order:

code

1response = send_request()2record safe status, content_type, request_id3if response is not documented success:4    follow documented error branch5else:6    parse and validate expected payload

Even a success status can contain invalid JSON if the server or intermediary is broken. Parsing and schema validation still need errors. The lesson is to avoid erasing the response context by jumping straight to a success parser.

Ask for minimal useful evidence

A public support request should include runtime version, sample version, operating system where relevant, the exact step, expected and actual behavior, safe status/error text, and a minimal fixture. It should not include working tokens, private payloads, or broad account dumps. An advocate can often reproduce a problem with synthetic input that preserves its structure.

If the learner supplies a secret accidentally, follow the platform's security response process rather than quoting it into more places. In the teaching artifact, show placeholders clearly and explain where values belong. Do not make a placeholder look like a working credential or embed a real one for convenience.

Change one relevant variable at a time. If the server printed 8081 while the client targets 8080, correcting that mismatch directly tests the connection hypothesis. Reinstalling dependencies, rotating tokens, and rewriting request code together make it hard to know which change mattered and can introduce new problems.

Turn a correction into reusable documentation

After resolving the immediate issue, update the page at the point where the mismatch begins. If the startup command prints a dynamic port, tell the learner to use that output rather than hard-coding a stale number. If a package release changed a flag, state the supported versions and verified command. A troubleshooting appendix should not compensate forever for incorrect main instructions.

A good error message names the current mismatch and a next action. Cannot connect to localhost 8080; confirm the server is running and compare its printed port is more useful than something went wrong. Avoid certainty beyond the evidence: connection refusal suggests the endpoint was not listening, but does not prove the learner forgot to start it.

Misconceptions and a second exercise

One misconception is that every setup failure needs reinstalling. Reinstallation can waste time and leave the original endpoint mismatch unchanged. Another is that retries fix every HTTP error. Repeating malformed input or unauthorized calls without a changed condition can add load without progress; rate-limited work needs the documented delay and a bound.

Exercise: the client reports unexpected token at the start of JSON; captured metadata shows 404, text/html and the URL ends in/events rather than/api/events. The model answer checks the documented route, corrects the endpoint, and repeats a bounded request before changing the JSON schema. Preserve the original safe metadata for a documentation fix. Award one point for identifying the response mismatch, one for the route hypothesis, one for a bounded confirming check, and one for avoiding credential exposure.

The advocate's skill is a small reliable diagnostic loop. It helps the learner recover and gives engineering a reproducible issue when the product or documentation is actually wrong.

Exercise and solution

Write the next step for three symptoms: command not found, valid HTTP response with 429, and a JSON parsing error after an HTML error page. The model answers check runtime installation/path, inspect rate-limit guidance and wait according to the contract, and inspect status/content type before assuming a successful JSON body. Award one point for each targeted branch and one for preserving the original error evidence.

Interview probe and wrap-up

How do you avoid blaming the learner? A strong answer describes the mismatch and verification step without assumptions about competence. Follow up with a bug in your published instructions. A weak answer repeats works on my machine or asks everyone to reinstall. Good troubleshooting narrows the cause and leaves the learner with a reusable diagnostic method.

Sources

docsGoogle technical writing: audience and documentsdevelopers.google.com docsGoogle code-sample style guidancedevelopers.google.com docsMDN HTTP 401 authentication semanticsdeveloper.mozilla.org docsMDN HTTP 404 response semanticsdeveloper.mozilla.org docsMDN Response.json parsing and errorsdeveloper.mozilla.org docsMDN HTTP 429 statusdeveloper.mozilla.org

Checkpoint

HTTP 404 with text/html is followed by a JSON parse error. Which first check best tests the observed mismatch?

ACompare the actual URL, route, status, and content type with the documented API response before changing the success parser.BAdd an empty-object fallback to the parser so later success fields can render.CIncrease retry count while keeping the same route and treating each parse failure as a transient transport failure.DChange the expected JSON field names to match the endpoint reference without first checking whether this is an API response.

Checkpoint

The local server prints port 8081. The client connects to 8080 and receives connection refused. Which next action isolates the observed cause?

AReinstall the runtime and dependency tree before checking the active server address.BChange the JSON parsing error handler to display a more detailed message.CAdd retries against 8080 without checking whether a process listens there.DAlign the intended client endpoint with the running server's documented address and make one bounded check.

Checkpoint

Which public issue packet lets a maintainer reproduce a failure while limiting unrelated private data?

AA screenshot of the error without the input, sample version, or failed step.BA full environment dump and request log from the user's production account.CVersion, exact step, safe error metadata, expected result, and a minimal synthetic fixture.DA successful output from the author's machine and a list of suggested reinstall commands.

Checkpoint

A 429 response includes retry timing under the API's documented rate contract. Which guide behavior fits?

AFollow the retry timing with a finite attempt budget and preserve operation identity where the API requires it.BRun parallel retries to increase the chance that one request reaches the service between limits.CUse a fixed short delay without reading the supplied timing because exponential backoff is only for server errors.DGenerate a fresh business-operation ID for every retry so the rate-limited request is treated as new work.

Checkpoint

A correction shows the main instructions use a stale port. Best documentation follow-up?

ALeave the main steps and add only a generic FAQ.BFix the point of mismatch and state how to use the server's actual printed endpoint.CTell every learner to infer the port without guidance.DRemove expected output to avoid future mismatches.

Can you choose a discriminating diagnostic step from runtime, connection, HTTP, and payload evidence without erasing context? 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.

Continue with Enzo Sign up free