PROFESSIONAL PRACTICE AND COLLABORATION

WRITING DOWN THE REASONS Earlier in this chapter you saw that good documentation explains why, not only what. Three kinds of short documents pay for themselves again and again. The first is a design note, a one-page explanation of a decision, such as why you chose a step limit of twenty-five and not fifty. The second is a runbook, a step-by-step guide for handling a known problem, such as what to do when a tool provider goes down. The third is a postmortem, a calm written review of an incident that asks what happened and how the system can be improved, without blaming any person. Each document should be short enough that a busy colleague will actually read it. Date each one, because an undated note cannot be trusted later. REVIEWING EACH OTHER'S WORK Because a harness is shared infrastructure, changes should be reviewed by a second person before they go live. A good review asks a few standard questions. Does the change have a test, and does the test fail without the change? Could the change let the agent do something it was not allowed to do before? Could it raise cost or slow responses? How would we notice if it went wrong, and how would we undo it? When you give feedback, comment on the work and not the person. When you receive feedback, thank the reviewer and look for the lesson, even when the comment stings. Teams that review kindly and carefully catch problems early and also teach each other quickly.