How to write a good software bug report

1. Locate and attach logs

Logs provide invaluable insights into the events and cause-and-effect relationships that affect software behavior. Logs document events during software and hardware operation.

When a workload fails, logs can usually shed light on what the workload was doing before it failed. For example, the software attempted a certain storage operation in the environment, and logs show that the desired storage resource wasn't available. This log data offers a strong clue that developers must implement better error handling routines. Similarly, log files contain details about processor exception errors that lead to software crashes, and other operations environment information.

QA and support staff should attach any available log files to the software bug report's issue tracking ticket. Systems management frameworks, which include application performance management software and other tools, offer a common source for various log files.

The software in development can also generate logs directly. Developers can add instrumentation and logging features directly into software builds. Internal logging produces granular records about critical behaviors, such as latency-sensitive network or processing activity. These logs can also trigger records of any errors, such as user input, storage, processor and other common fault areas.

2. Get into the necessary details

Before a developer can remediate any software bugs, he must successfully reproduce the reported problem. This task can be more difficult that it sounds, and developers might overlook or ignore issues that they cannot successfully reproduce.

While many defects are obvious, such as a menu misspelling, others only surface in specific processes or under certain circumstances. For this situation, an effective software bug report must include an array of details that can help developers understand precisely what was taking place at the time of the incident.

To write a good software bug report, start with an executive summary that highlights the problem and its impact. Then, describe the event in detail, and assess the defect's severity. Include detailed steps needed to reproduce the problem. In addition, the report can lay out actual versus expected results: what the software did and what it should have done.

A good software bug report should also include configuration details, such as the software version being tested and information about the platform running the software, as detailed in section 5. Differences in the platform can help explain or identify problems related to incompatible hardware or an undesirable firmware or driver version.

3. Include screen shots

A picture is worth a thousand words. When a developer can actually see the problem manifest, it provides an invaluable resource -- and enhances the tester's credibility. Attach any relevant image files to the defect report along with other information.

Screen shots are most valuable for bugs in the user interface, wrong or unexpected error dialogs, graphing issues and other visual problems. On the other hand, not all defects benefit from a visual, and a screen shot might not show the existence of deep or internal problems. For example, data entry elements in a UI must provide suitable security in terms of error handling and protection against malicious acts -- things a visual might not show.

Many tools can capture screen shots -- even the simple Microsoft Paint utility helps capture a visual. Some platforms, such as smartphones and tablets, might require third-party utilities.

4. Understand the defect impact

Much like their counterparts in the natural world, not all bugs are equally scary. A misspelling in a text dialog has a radically different priority than an exception error that crashes the software or loses valuable data. Bugs in production builds likely have higher priority than those discovered in older or experimental builds. Developers and IT incident response teams deal with many trouble tickets, so don't expect them to equally address every reported defect.

A software bug report must include prudent and pragmatic classification of the defect. A defect classification system aids in developer and IT support's workflow organization and prioritization. For example, a show-stopping software defect will go right to the top of a development team's queue, where multiple developers collaborate on a quick fix. Less-severe errors will get attention once high-priority defects are contained. Mere annoyances, or issues that have easy workarounds, might roll into future routine patch releases.

5. Mind the platform

Computers are remarkably diverse in their components, such as processor extensions, chipset, network ports and operating systems. Software imposes a set of requirements for hardware to ensure that a host computer system can run the application properly.

Testers typically evaluate a limited suite of computer systems with well-known and documented configurations. Beyond those systems, variations in system configuration can cause unexpected problems that should be addressed. Beta users are a good way to get a real-world assessment of a software build's stability and performance on a wide range of hardware configurations.

When defects arise in the curated test devices or the wider range of options, testers should include a summary of the underlying system's configuration in the bug report. Multiple tools can generate summaries of a system configuration. System Information utility in Windows 10 is one simple example of a tool that can export a system summary to a text file. Systems administration tools provide detailed system summaries of servers and other data center equipment.