1.4Tone, Structure, and Empathy in Defect Communication

Tone Guidelines

• Be factual, not emotional. "The page crashes when clicking Save" rather than "The Save button is completely broken and unusable."
• Assume positive intent. The developer did not introduce the bug on purpose. Complex systems have complex failure modes.
• Offer context, not criticism. "This might be related to the API change in PR #342" is helpful. "Someone clearly didn't think about this" is not.
• Acknowledge complexity. "I know this is a tricky area of the codebase" shows you understand the developer's challenges.

Structure That Reduces Cognitive Load

Developers process bug reports while context-switching from their own work. Make the report scannable:

• Use headers and bullet points, not walls of text
• Lead with the most important information (title + summary)
• Put reproduction steps in a numbered list
• Attach screenshots and logs inline, not as separate links
• Tag with severity and priority so triage is instant

Empathy in Practice

Empathy does not mean sugarcoating. It means recognizing that the person reading your bug report is a professional who cares about their work and wants to ship quality software. Write your report the way you would want to receive one.