JAVA-290 · Lesson 11 of 12 · 33 min
Documentation and handover
▶ Video coming soon A video version of this lesson is on the way.
On Monday, August 14, 2028, the booking website had been in production for four days and had taken nineteen bookings, all from repair-night regulars and customers who had seen the card at the counter. The team had eleven days left in the term, and Ingrid's question at the start of the week was not about features at all: on August 26, when Noemi starts a job and Thierry starts his last courses, who will run this, who will change it, and how will they know how? A capstone that only its authors can operate is not finished. It has been lent to the client until the first problem.
The week had a plan: Monday and Tuesday to write and check the documents, Wednesday, August 16, for the handover meeting with Leif, Odile, Tamsin and Kofi, and Thursday and Friday to fix what the handover found. The term's demo day was the Wednesday after.
Who reads what
Documentation fails most often by being written for nobody in particular, so that the operator has to read the developers' notes and the counter volunteers are given a description of the architecture. The team listed its readers first, and what each would be trying to do when they opened a document. Daniele Procida's Diátaxis framework helped them sort the result: it divides documentation into four kinds by what the reader needs. A tutorial teaches a newcomer by doing; a how-to guide gets a competent person through one task; reference describes the facts, completely and neutrally; and explanation discusses why things are as they are. Mixing them in one document is the usual reason a document is hard to use.
| Reader | What they are trying to do | Document | Kind |
|---|---|---|---|
| A new developer | Run it, change it safely, understand its decisions | README, CONTRIBUTING, ADRs, architecture overview | Tutorial, explanation |
| Leif, operating it | Deploy, roll back, answer an alert at night | Runbook, release checklist | How-to |
| Counter staff and volunteers | Check people in, handle a booking problem, help a customer by phone | Staff guide, one-page card | How-to |
| Odile | Understand the figures and what the website promises customers | Owner's summary, privacy notice | Explanation, reference |
| Anyone | Look up a route, a setting, a migration or a message | Generated reference pages | Reference |
Two rules kept the set manageable. Every document lived in the repository, beside the code, in Markdown, so that it was reviewed in pull requests and versioned with the software it described; the staff guide was also printed and kept in a folder under the counter. And whatever could be generated from the code was generated, because a hand-written list of routes or settings is wrong from the first change after it was written.
The README
The README is the front door. Its job is to tell a newcomer in one screen what the project is, and then to get them from a fresh clone to a running application and a passing test suite as quickly as possible. Hamza's test for it was brutal and useful: on Monday he gave a fresh laptop and the README to Kofi's nephew, a second-year computer science student who had never seen the project, and watched without helping. It took him 38 minutes and two questions to have the site running locally, and both questions became fixes to the README.
# Second Gear booking service
The booking API (api.secondgear.org) and the booking website (book.secondgear.org)
for Second Gear Cycles, a non-profit community bike shop. One Spring Boot service:
REST for the counter app, server-rendered pages for customers and staff.
## Run it locally
Requirements: JDK 25 (Temurin), Docker.
./scripts/dev-up.sh # starts PostgreSQL in Docker and loads generated test data
./gradlew bootRun # http://localhost:8080 for the site, /api/v1 for the API
Staff sign-in for local development: user `dev-counter`, password printed by dev-up.sh.
## Test it
./gradlew test # unit, slice and integration tests (needs Docker)
./gradlew browserTest # Playwright and axe-core; installs browsers on first run
## Find your way around
- docs/architecture.md: the hexagon, the adapters and the container diagram
- docs/adr/: why things are the way they are (start with ADR-001)
- docs/runbook.md: operating it, one section per alert
- docs/staff-guide.md: for the counter and repair-floor staff
- CONTRIBUTING.md: branches, commits, reviews, the Definition of Done
## Deploy it
Push a tag vX.Y.Z on main. The release workflow does the rest and waits for approval.
See docs/runbook.md#releasing.What this code does
The first paragraph says what the project is and who uses it before anything technical, because many readers stop there. The run and test sections are commands that can be copied, with one line of comment each, and the development password is generated by the start script rather than written in the file, so nothing secret is ever committed. The map of the docs folder tells each kind of reader where to go next.
The README was checked automatically too, in the same spirit as the Definition of Done. A small check in the build verified that the sections the team had agreed on were present, that every relative link pointed at a file that existed, and that every script named in a command was really in the repository. It caught two broken links in the first run, both to files that had been renamed in sprint 3.
import java.util.*;
import java.util.regex.*;
public class Main {
static final List<String> REQUIRED = List.of("Run it locally", "Test it", "Find your way around", "Deploy it");
static List<String> check(String readme, Set<String> files) {
List<String> problems = new ArrayList<>();
Set<String> headings = new HashSet<>();
Matcher h = Pattern.compile("(?m)^## (.+)$").matcher(readme);
while (h.find()) headings.add(h.group(1).trim());
for (String r : REQUIRED) if (!headings.contains(r)) problems.add("missing section: " + r);
Matcher link = Pattern.compile("(docs/[\\w./-]+?|CONTRIBUTING\\.md|scripts/[\\w.-]+)(?=[\\s:#)]|$)").matcher(readme);
while (link.find()) {
String path = link.group(1);
if (path.endsWith("/")) { if (files.stream().noneMatch(f -> f.startsWith(path))) problems.add("empty folder: " + path); }
else if (!files.contains(path)) problems.add("broken reference: " + path);
}
return problems;
}
public static void main(String[] args) {
Set<String> files = Set.of("docs/architecture.md", "docs/adr/001-site-adapter.md", "docs/runbook.md",
"docs/staff-guide.md", "CONTRIBUTING.md", "scripts/dev-up.sh");
String readme = """
# Second Gear booking service
## Run it locally
./scripts/dev-up.sh
## Test it
## Find your way around
- docs/architecture.md: the hexagon
- docs/adr/: why things are the way they are
- docs/operations.md: operating it
- docs/staff-guide.md: for the counter
- CONTRIBUTING.md: branches and reviews
""";
List<String> p = check(readme, files);
System.out.println(p.isEmpty() ? "README ok" : String.join("\n", p));
}
}missing section: Deploy it broken reference: docs/operations.md
What this code does
The check reads the level-two headings and compares them with the agreed list, then finds every path to a document, folder or script and looks it up in the set of files in the repository. A folder reference passes if any file lives under it, so docs/adr/ is fine while it holds at least one record. The draft fails twice: the deploy section is missing, and docs/operations.md is the runbook's old name from before it was renamed.
The runbook
The deployment course had given the booking API a runbook: one section per alert, each saying what the alert means, what to check, what to do and when to call someone. The website added four alerts, and Hamza wrote their sections with Leif, in the form Leif preferred, short enough to read on a phone in the dark. Each alert's definition in the Prometheus rules carries a link to its section, so the notification on Leif's phone opens the right page.
## OutboxBacklog
Fires when more than 20 messages have been due for over 10 minutes.
What it means: texts (confirmations, reminders, waiting-list offers) are not going out.
Customers are not harmed yet; reminders the evening before are the most time-sensitive.
Check, in order:
1. Grafana "Outbox" panel: is anything being sent? Look at sent per minute and failures.
2. Logs: `docker logs booking-api-green --since 15m | grep outbox` (phone numbers are redacted).
3. SMS provider status page (link in the shop's password manager entry).
Do:
- Provider down: nothing. The job retries with backoff and catches up; rows that give up
after five attempts are marked failed. After the outage, resend failed reminders for
tomorrow from Staff > Messages > Resend failed.
- Job not running (no "outbox: run" lines): check that exactly one color holds the leader
lock (runbook#leader-lock). Restarting the live color is safe.
- Failures say "invalid number": a bad row; the job skips it (finding S11). Tell Hamza.
Call Hamza if the backlog is still growing after 30 minutes.What this code does
The section starts with what the alert means for customers, because that decides how urgent it is at three in the morning. The checks go from the cheapest to the most effort and each action names the situation it applies to, so the reader matches what they see rather than reasoning from scratch. Escalation is a person and a time, not a vague instruction to ask someone.
A runbook decays the same way any reference does: someone adds an alert and forgets the section. Thierry's check runs over the Prometheus rule file and the runbook and fails the build if an alert has no section, a section describes an alert that no longer exists, or an alert's link points to the wrong place.
import java.util.*;
import java.util.regex.*;
public class Main {
public static void main(String[] args) {
String rules = """
- alert: BookingApiNotReady
annotations: { runbook: "docs/runbook.md#bookingapinotready" }
- alert: SitePageSlow
annotations: { runbook: "docs/runbook.md#sitepageslow" }
- alert: OutboxBacklog
annotations: { runbook: "docs/runbook.md#outboxbacklog" }
- alert: StaffLoginFailures
annotations: { runbook: "docs/runbook.md#staff-login-failures" }
- alert: RetentionJobMissed
""";
String runbook = """
## BookingApiNotReady
## SitePageSlow
## OutboxBacklog
## StaffLoginFailures
## ReminderJobStalled
""";
Map<String, String> alerts = new LinkedHashMap<>();
Matcher a = Pattern.compile("- alert: (\\w+)(?:\\s+annotations: \\{ runbook: \"docs/runbook.md#([\\w-]+)\" \\})?").matcher(rules);
while (a.find()) alerts.put(a.group(1), a.group(2));
Set<String> sections = new LinkedHashSet<>();
Matcher s = Pattern.compile("(?m)^## (\\w+)$").matcher(runbook);
while (s.find()) sections.add(s.group(1));
int problems = 0;
for (var e : alerts.entrySet()) {
String name = e.getKey(), anchor = e.getValue();
if (!sections.contains(name)) { System.out.println("no runbook section for alert " + name); problems++; }
if (anchor == null) { System.out.println("alert " + name + " has no runbook link"); problems++; }
else if (!anchor.equals(name.toLowerCase())) { System.out.println("alert " + name + " links to #" + anchor + ", expected #" + name.toLowerCase()); problems++; }
}
for (String sec : sections)
if (!alerts.containsKey(sec)) { System.out.println("runbook section " + sec + " has no alert (removed or renamed?)"); problems++; }
System.out.println(problems + " problem(s)");
}
}alert StaffLoginFailures links to #staff-login-failures, expected #staffloginfailures no runbook section for alert RetentionJobMissed alert RetentionJobMissed has no runbook link runbook section ReminderJobStalled has no alert (removed or renamed?) 4 problem(s)
What this code does
The alert names and their runbook anchors are read from the rule file with one regular expression whose second group is optional, so an alert without a link is still found. The runbook's sections are its level-two headings, and an anchor is expected to be the heading in lower case, which is how the repository's Markdown renderer makes anchors for single-word headings. The run finds four problems of three kinds: a new alert with neither link nor section, a link with the wrong anchor, and a section for an alert that had been renamed in sprint 4.
The staff guide
The staff guide was the document most likely to be used and least likely to be read in full. Counter volunteers change every few weeks, many are retired or in high school, and they read the guide with a customer waiting. Noemi wrote it as a set of short how-to sections named after tasks, such as Check in a customer or A customer says the website will not let them book, each a numbered list of steps with a screenshot, in the plain language that public-sector writing guides recommend: short sentences, common words, the reader addressed as you, one instruction per step.
To keep it plain as others edited it, she added a check that the build runs over the guide. It is crude, as all readability measures are, and it does not replace reading the guide aloud to a volunteer, which she also did. But it catches the two commonest ways technical writers slip, long sentences and words that only developers use.
import java.util.*;
public class Main {
static final Set<String> JARGON = Set.of("endpoint", "json", "deploy", "deployed", "database", "server", "api",
"status", "token", "session", "cache", "backend");
public static void main(String[] args) {
String section = "Check in a customer. Open Staff, then Today. Find the customer's time in the list. "
+ "Press Arrived next to their name. "
+ "If the customer is not on the list because the booking was made by phone and the database has not "
+ "yet been updated by the counter app's session, search by phone number at the top of the page. "
+ "If the status says CANCELLED, book them again if a time is free.";
String[] sentences = section.split("(?<=[.!?])\\s+");
int words = 0, longOnes = 0;
for (String s : sentences) {
int n = s.split("\\s+").length;
words += n;
if (n > 20) { longOnes++; System.out.println("long (" + n + " words): " + s.substring(0, 50) + "..."); }
}
Set<String> found = new TreeSet<>();
for (String w : section.toLowerCase().split("[^a-z']+")) if (JARGON.contains(w)) found.add(w);
System.out.printf("%d sentences, %.1f words per sentence, %d over 20 words%n", sentences.length,
(double) words / sentences.length, longOnes);
System.out.println("developer words: " + found);
}
}long (38 words): If the customer is not on the list because the boo... 6 sentences, 12.0 words per sentence, 1 over 20 words developer words: [database, session, status]
What this code does
Sentences are split after a full stop, question mark or exclamation mark followed by space, and any sentence longer than 20 words is reported with its opening so the writer can find it. The jargon list holds words that mean something precise to developers and little to a volunteer, and the check reports any that appear. The draft section has one sentence of 38 words full of developer words, which Noemi rewrote as two steps: If you cannot find the customer, search by phone number at the top of the page, and Phone bookings can take a minute to appear.
The real test of the guide came on Tuesday afternoon. Kofi gave it to two counter volunteers who had not used the staff pages, and asked them to check in three customers from the generated data on staging, handle a customer who had cancelled by mistake, and find out why a booking was missing. Both managed everything; one needed the guide for the missing booking and found the answer. Noemi watched and changed one screenshot that showed an older layout.
Generated reference
Reference pages are where generation pays most. The route table from lesson 7, the configuration properties from lesson 10 and the list of migrations were each produced from the code by a Gradle task and published with the documentation. The route table was the most useful, because it was generated from the running application's own mappings and security rules, so it showed, for every page, who could reach it; a mismatch between that and what the team intended would be a security bug. The example generates the table from a list of mappings and checks the rule the team cared most about.
import java.util.*;
public class Main {
record Route(String method, String path, String access, String story) {}
public static void main(String[] args) {
List<Route> routes = new ArrayList<>(List.of(
new Route("GET", "/", "public", "US-01"),
new Route("POST", "/book", "public", "US-02"),
new Route("GET", "/staff/today", "COUNTER, MECHANIC, MANAGER", "US-06"),
new Route("POST", "/staff/bookings/{id}/arrived", "COUNTER, MECHANIC, MANAGER", "US-06"),
new Route("GET", "/staff/figures", "MANAGER", "US-09"),
new Route("POST", "/my-booking/cancel", "public", "US-03"),
new Route("GET", "/my-booking", "public", "US-03"),
new Route("GET", "/staff/export", "public", "-")));
routes.sort(Comparator.comparing(Route::path).thenComparing(Route::method));
System.out.println("| Method | Path | Who can use it | Story |");
System.out.println("|---|---|---|---|");
for (Route r : routes) System.out.println("| " + r.method() + " | " + r.path() + " | " + r.access() + " | " + r.story() + " |");
routes.stream().filter(r -> r.path().startsWith("/staff") && r.access().equals("public"))
.forEach(r -> System.out.println("PROBLEM: " + r.method() + " " + r.path() + " is under /staff but public"));
routes.stream().filter(r -> r.story().equals("-"))
.forEach(r -> System.out.println("PROBLEM: " + r.method() + " " + r.path() + " belongs to no story"));
}
}| Method | Path | Who can use it | Story |
|---|---|---|---|
| GET | / | public | US-01 |
| POST | /book | public | US-02 |
| GET | /my-booking | public | US-03 |
| POST | /my-booking/cancel | public | US-03 |
| POST | /staff/bookings/{id}/arrived | COUNTER, MECHANIC, MANAGER | US-06 |
| GET | /staff/export | public | - |
| GET | /staff/figures | MANAGER | US-09 |
| GET | /staff/today | COUNTER, MECHANIC, MANAGER | US-06 |
PROBLEM: GET /staff/export is under /staff but public
PROBLEM: GET /staff/export belongs to no storyWhat this code does
The routes are sorted by path and then method, so the generated table is stable from one build to the next and its diffs in pull requests are readable. Each row shows who can use the route, as the security configuration decides it, and which story it serves. The last entry is the kind of thing generation exists to catch: a forgotten experiment, an export page from sprint 4 that was never secured and served no story, which the team deleted on the Monday the check first ran.
The export page was a genuine find. Thierry had added it in sprint 4 to download test data from staging as a spreadsheet, meant to delete it, and had not. It was never reachable in production, because the generated data existed only on staging and the page read nothing else, but on Leif's advice the team recorded it as a finding anyway, and added a rule to the route check that every route must name its story.
Handing over
A handover is the moment when responsibility moves from one group of people to another, and its documents matter less than the questions it forces. Who owns each part from now on? Who has access to what, and who should not any longer? What does the new owner need to have done once, with help, before they do it alone? The team wrote these down as a checklist and worked through it with Leif and Odile.
| Area | From August 26 | Done at handover |
|---|---|---|
| Operating the service | Leif, as for the API | Runbook walked through; one drill on staging |
| Changing the code | Hamza, as a volunteer maintainer, with Ingrid reviewing | Repository ownership and branch protection reviewed |
| Deciding what to build | Odile, with the Later page as the backlog | Backlog ordered; next three items agreed |
| Staff pages and the guide | Kofi for the counter, Tamsin for the repair floor | Guide tested with two volunteers |
| Customer data and privacy questions | Odile | Privacy notice and retention explained |
| Costs: server, SMS provider | Odile, paid by the shop | Billing contacts moved from Hamza to the shop |
At the handover meeting on Wednesday, August 16, Leif ran a short drill: Thierry triggered the outbox backlog alert on staging by pointing it at a fake SMS provider that refused every request, and Leif handled it using only the runbook, without any of the team speaking. He found the cause in four minutes and the resend button in another two. His only complaint was that the runbook's link to the provider's status page needed the shop's password manager, which he did not have; Odile added him to it on the spot. A drill like this tests the documents and the new owner at once, and it is far cheaper than finding out during a real outage.
Access was the part of the handover with the most consequences. During the term, the three students had needed access to the repository, to staging, to the SMS provider's test account and to the shop's channel; Hamza also had the production approver role he had used for releases. A capstone ends; access should end with it, deliberately and on a date, not whenever someone remembers. Thierry wrote the review as a program over the access list that the team kept in the repository.
import java.time.*;
import java.util.*;
public class Main {
record Grant(String person, String system, String level, LocalDate until) {}
public static void main(String[] args) {
LocalDate endOfTerm = LocalDate.of(2028, 8, 25);
Set<String> continuing = Set.of("Hamza", "Leif", "Odile", "Kofi");
List<Grant> grants = List.of(
new Grant("Noemi", "repository", "write", null),
new Grant("Noemi", "staging", "ssh", endOfTerm),
new Grant("Thierry", "repository", "write", null),
new Grant("Thierry", "SMS provider", "test account admin", null),
new Grant("Hamza", "repository", "maintain", null),
new Grant("Hamza", "production", "approver", null),
new Grant("Leif", "production", "approver", null),
new Grant("Kofi", "production", "approver", null));
for (Grant g : grants) {
String action;
if (!continuing.contains(g.person())) action = g.until() != null && !g.until().isAfter(endOfTerm)
? "expires " + g.until() : "REMOVE by " + endOfTerm;
else if (g.level().equals("approver") && g.person().equals("Hamza")) action = "review: keep while maintainer, re-check in 3 months";
else action = "keep";
System.out.printf("%-8s %-13s %-20s %s%n", g.person(), g.system(), g.level(), action);
}
long remove = grants.stream().filter(g -> !continuing.contains(g.person()) && g.until() == null).count();
System.out.println(remove + " grant(s) to remove by hand; rotate the SMS test key after Thierry's access ends");
}
}Noemi repository write REMOVE by 2028-08-25 Noemi staging ssh expires 2028-08-25 Thierry repository write REMOVE by 2028-08-25 Thierry SMS provider test account admin REMOVE by 2028-08-25 Hamza repository maintain keep Hamza production approver review: keep while maintainer, re-check in 3 months Leif production approver keep Kofi production approver keep 3 grant(s) to remove by hand; rotate the SMS test key after Thierry's access ends
What this code does
Each grant records a person, a system, a level and an optional end date, and the review compares it with the list of people continuing after the term. Grants of people who are leaving are removed by the end of the term unless they already expire by then, and a sensitive grant that stays, Hamza's approval of production releases, gets a date to be reviewed again rather than lasting forever by default. The last line is the habit from the deployment course: when someone who knew a key leaves, the key is rotated, even if nobody suspects anything.
Noemi and Thierry were sorry to lose their access, and said so, which Ingrid took as a good sign about the project. Odile asked whether they could stay on as volunteers. They could, she was told, but as volunteers with access granted again for a purpose and a period, not as a leftover from the course.
What the documents did not say
On Friday, August 18, Ingrid asked the team one more question: what would a new developer most need to know that was in none of the documents? After some thought they wrote a short page called Things we learned, which said, among other things, that the generated test data's fixed seed means a test that passes once passes forever, which can hide a test that depends on luck; that the counter app still writes the email column, so the planned contract step must wait for the counter app's next release; and that Tamsin reads the staff list on the tablet before nine on Saturdays, so a release on a Friday night is a bad idea. Ingrid said it was the most useful document in the repository, because it was the only one that could not have been written by someone who had not been there.
Exercises
Try it yourself
Check the README sections
Complete missing so that it returns, in the order of REQUIRED, the required section titles that do not appear as level-two headings (lines starting with ## ) in the README. Headings are compared after trimming and ignoring case.
import java.util.*;
public class Main {
static final List<String> REQUIRED = List.of("Run it locally", "Test it", "Find your way around", "Deploy it");
static List<String> missing(String readme) {
return List.of();
}
public static void main(String[] args) {
String readme = "# Booking service\n## Run It Locally\nsteps\n### Test it\n## Find your way around \n## Deployment\n";
System.out.println("missing: " + missing(readme));
}
}Try it yourself
Review access at the end of the term
Each grant is person system. People in staying keep their grants. Complete main so that it prints each grant of someone leaving as remove person system, then the number removed, and finally the systems for which a key or password must be rotated, which are the systems in shared that a leaving person had access to, in alphabetical order.
import java.util.*;
public class Main {
public static void main(String[] args) {
List<String> grants = List.of("Noemi repository", "Noemi staging", "Thierry repository", "Thierry sms",
"Hamza repository", "Hamza production", "Leif production");
Set<String> staying = Set.of("Hamza", "Leif");
Set<String> shared = Set.of("sms", "staging");
System.out.println("0 removed");
}
}Common mistakes
MistakeWriting one document for every reader.
InsteadList the readers and their tasks, and write tutorials, how-to guides, reference and explanation separately.
MistakeKeeping documents outside the repository.
InsteadKeep them beside the code, reviewed in pull requests and versioned with it.
MistakeHand-writing lists of routes, settings or migrations.
InsteadGenerate reference from the code and check it in the build.
MistakeA runbook with no link from the alert.
InsteadLink every alert to its section and check that alerts and sections match.
MistakeAssuming a guide is clear because its author understands it.
InsteadTest it with real readers doing real tasks, and with a drill for the operator.
MistakeLetting access outlive the project.
InsteadReview every grant at handover, remove what is no longer needed on a date and rotate shared keys.
Summary and key terms
- The last week before demo day turned the website from something its authors ran into something others could.
- The team listed its readers, a new developer, the operator, counter staff and the owner, and used the Diátaxis kinds, tutorials, how-to guides, reference and explanation, to decide what each document should be.
- Documents live in the repository and are checked in the build: the README for required sections and working references, the runbook for a section and correct link for every alert, and the staff guide for long sentences and developer words.
- The README was tested by a newcomer, the staff guide by two volunteers, and the runbook by a drill in which Leif handled an outbox backlog on staging alone.
- Reference pages, such as the route table with who can use each route, are generated from the code, which exposed a forgotten, unsecured export page on staging.
- The handover recorded owners for operations, code, priorities, staff pages, privacy and costs, and an access review removed the leaving students' grants, set a review date for Hamza's approver role and rotated a shared key.
- A page of things learned captured what no generated document could.
- Diátaxis
- Daniele Procida's framework of four kinds of documentation: tutorials, how-to guides, reference and explanation.
- Tutorial
- Documentation that teaches a newcomer by guiding them through doing something.
- How-to guide
- Documentation that takes a competent reader through one task.
- Reference
- Complete, neutral description of facts such as routes, settings or messages.
- Explanation
- Documentation that discusses why things are as they are.
- README
- The front-door document of a repository: what it is, how to run and test it, where to go next.
- Runbook
- Operating instructions, one section per alert or task, for the people who run a system.
- Plain language
- Writing with short sentences, common words and one instruction per step.
- Handover
- Moving responsibility for a system to new owners, with documents, practice and access changes.
- Access review
- Checking who has access to what and removing grants that are no longer needed.
Practice problems
Work each problem on paper first, then reveal the answer to check.
Why did Hamza give the README to someone who had never seen the project?
Show answer
Only a real newcomer can show where the instructions fail; his two questions became fixes.
Why does every alert link to its runbook section?
Show answer
So the notification opens the right instructions at once, and a build check can confirm the link and section exist.
What did the plain-language check find in the staff guide?
Show answer
A 38-word sentence full of developer words, which was rewritten as two short steps.
How did generated reference expose a security problem?
Show answer
The route table showed an export page under /staff that was public and belonged to no story.
Why was the SMS test key rotated even though nobody was suspected?
Show answer
Someone who knew it was leaving, and rotating keys when people leave is the habit, not a judgment of them.
Lesson quiz · 5 questions
Score 60% or more to complete this lesson.
Create a free account to save your progress, take quizzes and earn a certificate.