PROFESSIONAL PRACTICE AND COLLABORATION

DOCUMENTATION THAT EXPLAINS WHY Code tells a reader what a system does. It rarely tells them why it was built that way. A short design-decision document fills that gap. Our standard template has four parts. The Problem says what needed solving. The Alternatives Considered lists other options and why they were set aside. The Chosen Approach says what was decided. The Reasoning explains why, so that a future reader who was not in the room understands. Here is a small worked example from the lab, written the way we want you to write yours. Problem: the Stage 5 supervisor must handle a tool that is temporarily failing without either giving up instantly or repeating forever. Alternatives considered: no retries at all, which fails on every brief hiccup; retries with a fixed wait, which can hammer a struggling service; and unlimited retries, which can loop forever. Chosen approach: up to four attempts with the wait doubling each time, starting at 0.2 seconds, and a clear tool_unavailable stop after the last attempt. Reasoning: temporary faults often clear within a second or two, so a few quick retries recover most of them cheaply, doubling the wait avoids overwhelming the service, and a firm attempt limit guarantees that a real outage ends the run quickly and loudly, which we proved by simulating an outage and counting four retry events. Notice that the reasoning cites evidence. Documents like this age well. Months later, when someone wonders whether the limit of four can be raised, the document tells them what was weighed.