When reporting a bug.

Introduction

When reporting a bug, or a request or request for specifications to a development engineer, related departments, external development destinations, etc., the points cannot be accurately communicated and improvement cannot be achieved. It may take some time. It is said that not only users but also engineers who are asked to review or are involved in QA may be confused by bug reports. Therefore, this time, we have summarized the points for efficient and comfortable spinach (reporting, contacting, and consultation).

Things to check before [before] reporting a bug

3 points to keep in mind + α

When you are operating an IT system or software and a problem occurs, the first thing to keep in mind is to be “calm”. If the software behaves unintentionally, or if there is a bug such as a screen freeze, take a deep breath and calm down. A calm report will shorten the time to solve the problem.

If you tell the points to be told in the bug report first, there are three things: “what happened”, “procedure to reproduce”, and “what kind of operation was expected (intention)”.

A good bug report is a clue to a quick problem finding for an engineer. Even seemingly complicated events are often surprisingly easy once the cause is known. Accurate reporting is required for that purpose. Also, respect and respect the other person with a polite tone so that you can communicate smoothly. This is also an important point.

1. Try to write “briefly”

It is most important to write clearly and concisely so that it can be communicated to the engineer. You don’t have to be aware of Belles-lettres. Rather, it seems that it is often better to avoid unnecessary expressions. You can simply write “-was”, “-was”, and “-was”. In some cases, bullet points are preferable. Since it is a scene where “reports that can be conveyed” are required rather than beautiful sentences, it is better to write them plainly without any effort.

2. Write without using “unique term”, “dialect expression”, or “department local language”

Try not to use “unique terms” or “unique technical terms” that are valid only for you or within your department. Naturally, unique expressions are not transmitted to others or people outside the department. Please read it once before submitting it to ensure you are not using your expressions. However, this can be an unexpectedly high hurdle. It seems that the best measure is to avoid using original expressions regularly.

3. Use the function name and screen display words as they are

It is similar to avoiding original terms, but the names such as software functions and the words (keywords/messages) displayed on the screen are used as they are. Please note that changing words or misunderstandings can be misleading. For example, “Install” may be referred to as “In stool”, “Instal”, and “gif (Graphics Interchange Format)” may be referred to as “Gif”. It’s often not a problem, but in rare cases, it can be a hassle to check. If you don’t know, you can reduce the possibility of misunderstanding by using the original English character display as much as possible.

+ α. Do not state “unique views” on the problem as much as possible

It is not advisable to guess and describe the cause of the problem that occurred. Since the situation is reported because it cannot be resolved in the first place, there is a possibility that the original opinion (guess) may be incorrect, and it may become a mislead and hinder the investigation of the cause. The point is not to make the report text a “deduction quiz”. If you want to tell, make it clear that it’s a guess.

Points when [reporting] a defect

Will the problem be reproduced?

However, only the person who encountered the phenomenon can understand what kind of problem is occurring just by reporting that “the screen is strange”, “behavior is strange”, “cannot connect to the Internet”, or “freezes”. In such cases, the reporter and the reporter must start by understanding “what is this report”, and both the reporter and the reporter are just wasting time. To avoid such a situation, collect materials before reporting whether the problem is reproduced or an accident.

If possible, take a screenshot or take a picture of the problematic screen with your smartphone’s camera, and then see if the problem can be reproduced. If you do the same thing and the problem occurs, make a note of it, and if the problem is reproduced and a message, etc. is displayed, save the screen.

Check help and FAQ

In the case of the version that has already been released, the problem that occurred is likely to be a defect as it is, but in the case of the version under development, if the development team is aware of the problem, detailed reporting is unnecessary. You may.

Make sure that the bug you are facing is not mentioned in the help, FAQ, development notes, updates, and other documentation. It’s a waste to spend a lot of time reporting cases that are already known. In addition, the behavior that seems to be a malfunction may be specified for some reason. Let’s check these points in the documents.

(1) Report: Situation / Phenomenon

Check the above and report if it seems to be a problem. I will describe in detail what kind of trouble occurred. As an example, instead of “the input screen crashes”, it is written as “the browser crashes when you enter characters on the input screen”. It also reports the environment in which the problem occurred, as far as we can tell.

• Version information of the software in which the problem occurred
• Information on the environment of occurrence (OS, OS version, PC used, etc.)
• Information such as error messages displayed on the screen (saved above)
• Other additional notes, etc.

(2) Report: Reproduction procedure

Describe the procedure in which the problem occurred in as much detail as possible. It seems that bullet points are often more suitable than long sentences.
for example,

1. Log in to the service
2. After entering characters on the input screen
3. A message is displayed on the screen
4. Browser stopped responding

It doesn’t matter if the sentence is interrupted in the middle, such as, so the procedure of occurrence is described in a numbered bullet point.

Ideally, the engineer who receives the report can operate in numerical order to reproduce the problem. This is the core of the report. As an additional explanation, it is good to add information such as whether the above operation reproduces 100% or how many times it occurs.

The point is information such as messages displayed on the screen. If possible, attach a screen capture or a screenshot taken with a smartphone camera to make it easier to convey the explanation. If you can submit application or system logs, include this as well.

(3) Report: Expected behavior

Do the operation you are reporting and tell them what you were expecting. The “expected behavior”, that is, what the reporter’s intention was, is important information. The engineer who receives the report can understand why the reporter felt that the behavior was defective, which helps to get a complete picture of the report and makes it easier to come up with a solution.

Precautions when [contacting] a problem

Be aware of “where” and “who” the report destination

The wording, submission method, and contact method of the report will differ depending on whether the report destination is “internal”, “external”, “inside the community”, or “inside the team”. Be aware of who (reporter) submits to “who (reporter)” in “where (position)”, and try to communicate smoothly according to the TPO.

Recently, there are many cases where bug reports are operated using a ticket system, chat system, etc., and even though there is a system, if you report by email or phone, the response becomes irregular and hinders the overall progress. It will be. Be sure to choose the appropriate method and report. If you don’t know, it may be a good idea to first ask “Where should I report?”

When to convey a request or [consult]?

The point of request is similar to reporting a bug

The basics of communicating a request or requesting a feature are similar to reporting a bug. The difference is that it conveys “current behavior”, “expected (desired) behavior” and “merits”. In the case of a bug report, the point is to convey the facts that are happening as they are, but in the case of a request, we will focus on what new benefits can be gained by changing the current behavior.

Clarify “what action” and “what you want” at “when”

I will describe the procedure up to the desired operation so that the engineer can reproduce it. It seems that numbered bullets are often suitable.
For example, now

1. Log in to the service
2. After entering characters on the input screen
3. A message is displayed on the screen
4. Result A is obtained

In that case, I would like you to change this “3.” like this, or change “4.” to a different result B. It is not necessary to write it by force, but it seems better to “report in an easy-to-understand manner so that it can be communicated.” Also, avoid emotional expressions. Smooth communication is important.

Describe the benefits of the request/request

Be sure to state who has the benefits of fulfilling the request/request, and what risks and negatives can be avoided. This is a very important point. Unlike the case of a defect that requires an early response, in most cases, whether or not it can be adopted is examined in the case of a request/request. At this time, if you do not know the benefits you can obtain, it may be judged as an individual preference and rejected.

When requesting a function that has never existed before, it seems that it is often passed through unless the merit is clear. When describing the merits, it is advisable to describe them carefully, clearly, and concretely.

Create a [system] to send and receive reports

Prepare a template for reporting/requests in advance

If you prepare a template for reports and requests that suits your development style in advance, it will be easier to make a call with fewer points. You can see many cases by searching for “defect report template” and “request template”, and you can also find distribution sites.

The point of preparing the template overlaps with the notes of [Contact]. It is important to consider and consider who (reporter) submits to “who (reporter)” of “where (position)”.

Have tools for reporting and requests in place

Efficiency will improve if there is a single point of contact for receiving reports and requests. In the past, email was the main method, but recently communication tools such as Backlog, slack, and Chatwork have been developed, so it seems better to predetermine the tools and rules to be used for reporting. In most cases it’s available, so you’ll want to sort out the right tools, rules, and reporting flow. When accepting from outside the department or department, it may be more efficient to prepare a posting form for reporting. It seems better to choose the method that suits your team’s style.

summary

Bug reports, bug reports, requests, and requests are nothing but communication between people. As I mentioned several times in the text, the first point may be to be aware of smooth communication.

If you ever want to know about similar things, check out the Facebook page Maga Techs