The person reading the problem description should not have to be a detective to determine what the problem is. Right up front in the description, describe exactly what you perceive the problem to be. Some descriptions detail a series of actions and results. For example, “I hit the enter key and action A happened. Then I hit the back arrow and action B happened.
Then I entered the “xyz” command and action C happened.”
The reader may not know if you think all three resulting
actions were incorrect, or which one, if any is incorrect. In all cases, but especially if the description is long, you need to summarize the problem(s) at the beginning of the description. Don’t depend on an abstract in a different field of the defect report to be available or used by everyone who reads the problem description. Don’t assume that others will draw the same conclusions that you do.
Your goal is not to write a description
that is possible to understand, but to write a description that cannot be misunderstood. The only way to make that happen is to explicitly and precisely describe the problem rather than just giving a description of what happened.
| Precise Example | Defect Remark |
| Don’t: In this example, it is hard to tell if the problem is 1) the twinax port not timing out or 2) the printer not returning to ready or 3) the message on the op panel. | Issuing a cancel print when job is in PRT state (job is already in the printer and AS/400 is waiting to receive print complete from printer) causes the Twinax port to not time out. The printer never returns to a READY state and indefinitely displays "PRINTING IPDS FROM TRAY1" in the op-panel. |
| Do: Precede the description with a short summary of exactly what you perceive the problem to be. | Canceling a job while it is printing causes the printer to hang. Issuing a cancel print when job is in PRT state (job is already in the printer and AS/400 is waiting to receive print complete from printer) causes the Twinax port to not time out. The printer never returns to a READY state and indefinitely displays "PRINTING IPDS FROM TRAY1" in the op-panel. |
