How to Write an Effective Problem Report

I believe you’ll agree with me that reporting problems isn’t the best way to engage in human-to-human communication. There are certainly better opportunities to fulfill our need for connecting with others and sharing our emotions. Considering this, I believe a problem report should be written in a way that a support person can understand your issue without the need for unnecessary communication roundtrips.

While we often recognize that filing issue reports isn’t just an unnecessary formality, you might view writing problem reports in an issue tracker as an act of bureaucracy to appease the souls of some pedantic individuals. However, you should consider that the person reading your report isn’t familiar with your job tasks and might not possess your unstructured text reading abilities. So, the fact that a well-written and structured report satisfies their souls doesn’t mean you can save time by not carefully preparing the problem description.

There’s no need to reinvent the wheel. The following issue report has been utilized by numerous teams and companies. In my humble opinion, an easily comprehensible report consists of the following five sections:

• Description (no need for header)
• Steps to Reproduce:
• Actual Results:
• Expected Results:
• Additional Information:

Here’s a sample report:

I couldn't clone a new repository using the CLONE service. All my requests result in an error.

Steps to Reproduce:
1. Open the service UI as a user with DEVELOPER privileges.
2. Open the clone dialogue.
3. Paste the git repository URL.
4. Click the "Clone" button.

Actual Results:
The process ends, and when I check the repository overview, my repository isn't there.

Expected Results:
If the repository can't be cloned, I want to see the error message.
However, the repository I was trying to clone should be copied without any errors.

Additional Information:
- Tested repository URL: https://example.git.org/johndoe/hello_world