Better Software - September 2008 - (Page 33) Table 2: Neutralize example information that will be helpful to the developer. In the long run, this added bit of professionalism will gain you respect and credibility. Read over your problem description before submitting it, and remove or restate those comments that could be interpreted as being negative toward a person. Table 2 is a response to a developer’s returning a defect for more information and requesting more details on what values caused the problem. PreCise The person reading the problem de- scription 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 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 it is possible to understand but to write a description that won’t 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, as shown in table 3. Table 3: Precise example www.StickyMinds.com SEPTEMBER 2008 BETTER SOFTWARE 33 http://www.StickyMinds.com
For optimal viewing of this digital publication, please enable JavaScript and then refresh the page. If you would like to try to load the digital publication without using Flash Player detection, please click here.