Write bug reports from facts first
A Good Bug Report Leaves Less Room for Imagination
When I mentor younger engineers, I often see bug reports that begin with a conclusion: "The database is slow," "the network is flaky," or "the user entered something strange." Those statements may eventually prove correct, but they are poor starting points. They ask the next person to investigate a theory instead of a fact.
Record the Small Scene A useful report is usually a small, reproducible scene. What command was run? Which version was installed? What input was supplied? What did the program print, and what should it have printed? If the failure appears only once in ten attempts, say that too. "Failed once" is not a weakness in the report. It is an important property of the failure.
Keep the First Explanation Separate The report can include a suspicion, but label it as a suspicion. This distinction matters because explanations have a way of becoming invisible assumptions. Once somebody writes "probably a permissions issue," later readers may stop checking timestamps, environment variables, or the actual account running the process.
Why This Still Matters Old systems taught us this lesson rather directly. A short line in a console log, paired with the exact input and machine state, could save an afternoon. A long description of what the operator believed was happening could waste one.
The discipline is unchanged in modern systems, even when the evidence is spread across application logs, containers, dashboards, and ticket comments. Capture facts before arranging them into a story. The story may be wrong. The facts are at least available for correction.
A bug report is not a confession and not a courtroom argument. It is a handover note to the next engineer. Make that person's first five minutes easier.