Lesson 1 of 4 · 60 min
Start with what the developer must do
Write an audience contract and select the right form of technical content.
A developer does not arrive at documentation with one universal need. A beginner may want a guided first success. An experienced user may need one command to repair a failure. Another reader may need exact parameter behavior or an explanation of why a design works. Mixing all of these into one page can make every task harder.
Define the audience by prior knowledge and intended action, not only job title. Backend engineer can describe someone who has never used webhooks or someone who operates them daily. A useful audience contract states what the reader already understands, what tools they can use, and what they should be able to do at the end. The outcome should be observable.
Diataxis distinguishes tutorials, how-to guides, reference, and explanation. Use this distinction to decide what belongs on the page. A tutorial controls the learning path and provides a reliable first experience. A how-to guide assumes more knowledge and solves a specific task. Reference needs precision and completeness within its scope. Explanation develops a mental model and the trade-offs behind it.
Google's technical writing material emphasizes audience, scope, and organization around reader needs. The practical consequence is that every section should help the declared reader reach the declared outcome. A long history of an API may be interesting, but it can interrupt a reader who is trying to verify a webhook signature before lunch.
Worked example
A fictional developer platform wants content about event delivery. The audience is a developer who can run a local server and understands HTTP but has never handled duplicate events. The outcome is to process a repeated event without creating a second local effect. The tutorial uses a local fixture with event E1 delivered twice and produces one stored result.
A separate reference page describes event fields and delivery guarantees. A how-to page covers replaying failed deliveries. An explanation page discusses why acknowledgement loss causes duplicates. The tutorial links to these resources at the point where they answer a likely next question rather than embedding every detail in the first five minutes.
Write the audience contract as a usable artifact
A role label is a starting clue, not a complete prerequisite list. A backend engineer may know HTTP but have never run Python. A technical writer may understand event semantics but lack a local development environment. Identify the knowledge and tools needed for this specific result, and offer a route around a missing prerequisite where possible.
code
1Audience: developers who understand HTTP requests and responses2Prior knowledge: loops, maps/sets, one local script3Tools: Python3 or ability to trace a short Python example4Outcome: distinguish repeated event identity from equal payload values5Evidence: predict two fixtures and explain one changed failure boundary6Outside scope: live provider authentication and production concurrencyThis contract gives both author and reader a way to decide whether the page fits. A reader who only needs the retry header syntax can go to reference rather than work through the whole tutorial. A learner without local Python can trace the fixture on paper for the reasoning exercise, while the runnable path still states its runtime requirement.
The outcome should use an observable action. Understand webhooks is too broad to assess. Predict whether these deliveries create one or two effects is specific. It also helps the author choose a fixture that exposes the relevant distinction instead of adding unrelated API features.
Build a content routing map
| Reader question | Primary content form | Evidence of a useful page |
|---|---|---|
| How do I get a first successful event? | Tutorial | Known starting state leads to verified first result |
| How do I replay one failed event? | How-to | Procedure solves the task with preconditions and recovery |
| What values can event_id contain? | Reference | Precise contract, examples, and limits |
| Why can delivery repeat after acknowledgement loss? | Explanation | Causal model connects failure to behavior |
The forms can link to each other without becoming isolated silos. A tutorial can briefly explain why an event repeats, then link to deeper discussion. A reference can link to a how-to when a parameter is commonly used in a procedure. The decision is about the page's main purpose and reading path, not a ban on every other sentence type.
Avoid turning a tutorial into a menu of choices before the first success. A beginner who has not seen the mechanism cannot yet evaluate every storage option. Choose one controlled path, state the assumption, and leave alternative production choices for an explicit next step.
Design prerequisites that support the result
A prerequisite should be necessary and testable. Instead of install everything, ask the reader to run the runtime version command and compare it with the supported range. Instead of know programming, show the loop and set concepts the lesson assumes. This reduces avoidable setup failure and helps the learner decide whether to take a short preparation route.
A mixed audience does not require lowering every lesson to the same level. Provide a short setup/preflight branch and an optional deeper extension. Keep the core outcome common so the room can discuss the same result. Experienced participants can analyze concurrency limits while newer participants trace the local identities.
Do not hide an account or payment requirement in step eight. If the learning goal can be taught locally, choose that path. If the actual goal is authenticated integration, state the sandbox and permission requirements before starting and explain what the local alternative does not verify.
Review the page against its contract
For each section, ask whether it supplies a prerequisite, performs the target task, explains the observed result, or supports recovery. A long product history may belong elsewhere. A parameter table may be necessary at the point of use, but exhaustive unrelated options can distract from first success.
A second reader can perform a contract review without running the code: identify the target outcome, required tools, expected output, and next action after a failure. A clean editorial pass does not prove execution, but it can detect missing expectations and unexplained terms before a run.
Misconceptions and a second exercise
One misconception is that advanced vocabulary makes content suitable for advanced readers. Precision and relevant tradeoffs matter more than extra jargon. Another is that reference content is simply a shorter tutorial. A reference must answer exact contract questions without requiring the reader to follow a learning sequence.
Exercise: a page titled first event tutorial opens with fifteen authentication variants and no sample output. Rewrite its opening plan. State one supported sandbox path, required runtime and account context, the exact first result, and links to alternative authentication reference. Award one point for each. Do not remove necessary security conditions; move optional branches so they do not block the chosen path.
In an interview, defend the content form through the developer's task. Explain what the reader knows, what they will do, and what evidence will show success. That reasoning is more useful than choosing a format because it is common on a content calendar.
Exercise and solution
Classify four reader requests: help me get my first event, what does event_id mean, how do I replay yesterday's failure, and why can an acknowledged event arrive twice. The model answers are tutorial, reference, how-to, and explanation. Award one point for each, then ask the learner to state one prerequisite for the tutorial. A correct label without a reader outcome is only partial understanding.
Interview probe and wrap-up
How would you adapt the tutorial for experienced infrastructure engineers? A strong answer removes basic HTTP setup, adds precise delivery and failure assumptions, and retains a verifiable outcome. Follow up with a mixed workshop audience. A weak answer only adds more terminology. Teaching begins with a concrete contract about who will learn what and how you will know they learned it.
Sources
docsGoogle technical writing: audience and documentsdevelopers.google.comdocsDiataxis documentation formsdiataxis.frdocsGitLab Developer Advocate rolehandbook.gitlab.comCheckpoint
Which outcome is most observable for this lesson?
AUnderstand all webhook architectures.BKnow the product well.CPredict whether supplied repeated/distinct IDs create one or two effects and explain why.DRead the page to its end.
Sign up free to answer and see whyCheckpoint
An experienced user asks for exact event_id limits. Best primary form?
AReference with the precise contract.BA full beginner setup tutorial.CA broad explanation of messaging history.DA general troubleshooting sequence without field details.
Sign up free to answer and see whyCheckpoint
A first-run tutorial presents several supported authentication variants before any result. Which revision best reduces initial decisions while preserving valid access?
AMove all authentication setup after the first API call so the reader sees the endpoint first.BKeep all variants inline but combine them into one command without explaining which grant it uses.CUse the presenter's existing credentials and defer the learner's access setup to an appendix.DChoose one supported path, state prerequisites, and link alternatives at relevant points.
Sign up free to answer and see whyCheckpoint
Half the audience lacks the assumed runtime. The core objective is to trace duplicate-event handling, with execution as a separate outcome. What should the author do?
ASpend the whole core session installing the runtime, then count viewing the final output as the reasoning assessment.BProvide a stated preflight/setup or tracing route, preserve the reasoning check, and record execution separately.CUse a hosted notebook with different persistent state but keep the original reset instructions without checking equivalence.DHave learners copy the presenter's final total and record that as successful local execution.
Sign up free to answer and see whyCheckpoint
A tutorial's core result needs one supported setup path. Readers also need a long comparison of alternative delivery architectures. What placement best supports both needs?
ARequire the full comparison before the first run, even though its decisions do not change this fixture.BMove all explanations, including the reason event identity matters, into a separate reference page.CKeep short causal explanations beside the core steps and link the longer architecture comparison at the decision boundary.DPut the comparison after the command but remove expected output to keep the page short.
Sign up free to answer and see whyCan you turn a broad developer audience into testable prerequisites, a precise outcome, and a content route that fits the reader's task? 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.