Hello, my name is Natalia, I am a testing engineer at Docsvision.
Sometimes, when I look at errors recorded by new (and sometimes old) testers, my hand automatically reaches for a face. Only one thought arises in the head:



"What? What have I read now? ”
')
There is a lot of information on the Internet about WHAT must be present in the bug report. And I decided to share with you my thoughts on HOW you need to write a bug report, so that it is clear what you are writing about.
First of all, I wrote this for testing engineers and technical support engineers who send us bugs sent by customers. Also, my article can help formulate a description of the problem encountered when contacting the user for technical support: a correct description allows you to process the incident faster without additional questions.
In general, it may be useful to read to all members of the software development team, who record their communication in the bug tracking system.

I will give an example so that it becomes clear from what my hand flies to the face at the speed of light:

“In the file control, if there are enough files, some of the names are not fully displayed.
Create any document UD. On the Registration tab in the Add file field, right-click the mouse, and select several files. The second option is to drag a few files into this field. In resutat, if several files, the names do not fit completely. Only if you expand the card to the full screen, you can see everything completely. The line with the file should be transferred to the next line in the control, but this does not happen. "
(Spelling and punctuation preserved).

Some incredible piece of text, consisting of a continuous stream of consciousness.
Colleagues! You write for other people who have a completely different head and a completely different way of thinking. You must write understandably!

Here are the top 10 rules of good tone, which I adhere to myself and which I recommend to my colleagues:
1) First the verb.
2) The "What-Where-When" principle.
3) Impersonal.
4) Simple designs.
5) Without further ado.
6) Reduce the obvious.
7) Simplify the description of the complex action.
8) Point by point.
9) Uniqueness.
10) Reread.

1. First the verb

Master Yoda from Star Wars spoke in such a way that it was not easy to understand him the first time. His speech was based on the principle “object-verb-subject”.
“When you turn 900 years old, you will not look young either.”
In our speech, the verb stands at the beginning (if any).

Example :
Bad - "Open copied card for editing."
Good - “Open copied card for editing”.

2. The principle of “What-Where-When”

This principle is well known - you first need to write “what”, and only then “in what place” and “under what conditions”. It works best when making a brief description of the error.
What's happening? - “A card is not created”, “An unhandled exception is thrown”, “A database is not created”.
Where is going on? - “In the virtual folder”, “On the History tab”, “In the context menu”.
When does it happen? - “By pressing a button”, “After changing the card status”, “When saving changes”.

Example :
Bad - “In the report, when you add a comment file, the text comment is erased.”
Good - "Text comment is erased in the report when adding a comment file."

3. Impersonality

A description of the error is not a chronicle of your actions, but a guide for another person. Remove yourself from the description.

Example :
Bad - "Press the button", "Open the page."
Good - “Press the button”, “Open page”.

4. Simple designs

Compound and complex sentences, participial and verbal participations complicate the perception of the text. The simpler the sentence is built, the better.

Example :
Bad - "On the toolbar there is a button with a gear that opens a menu of two items, when you hover over it does not appear a tooltip."
Good - “Hover the mouse over the button with the gear on the toolbar - the tooltip does not appear.”

5. Without further ado

When I watch Soviet films, in which every second phrase has become winged, I admire how carefully the speech of the characters is worked out. Not a word too much. Every word is worth its weight in gold. You also need to make a description of the errors - each word must mean something.
Habitual speech is rich in epithets, pronouns, prepositions that do not add any additional meaning. If it is very difficult to cope with your own brain, write down the whole stream of consciousness as it is, and then remove from the text those words that do not carry a semantic load.

Example :
Bad - "For some reason, the change of values ​​in the field works quite strange - in fact, the field is updated after a certain period of time."
Remove the words "For some reason", "pretty", "weird", "in fact." They do not contain valuable information and can be removed from the description without losing meaning. The phrase "some period of time" can be replaced by a shorter synonym.
Good - "Updating values ​​in the field is delayed."

6. Reduce the obvious

Some actions are not specific to the system under test. For example, saving an object, closing a window, invoking a context menu, double-clicking, launching an application. These actions are usually intuitive, so when describing an error you should not focus on them.

Example :
Bad - “Find the application shortcut on the desktop, click on it 2 times with the left mouse button.”
Good - “Open app by label.”

7. Simplify the description of the complex action

Suppose there is some specific operation in the system under test. New testers or developers who are poorly oriented in the interface may not know how to perform such an operation. Therefore, to describe the implementation of this task is possible through the description of simple actions that will help her perform.

Example :
Bad - “Reconcile document”, “Perform property synchronization”.
Good - “Press the button“ Agreed ”on the toolbar of the document card”, “Select the command“ Synchronize properties ”in the context menu of the object”.

Yes, it increases the description. But it reduces the playback time by reducing the number of questions like “And how to do it?” To the author of the error.

Important! What is obvious to you is not always obvious to another person.
Personally, I use 2 methods of assessing the obviousness of my description:
1) Imagine seeing the interface for the first time;
2) Predict questions that may arise from the reader.

8. Point by point

Good practice is to break the playback steps into points. This gives 2 main advantages:
1) It is easier to walk through the playback steps.
2) It is possible to refer to a certain item.

Example :
1) Open the directory categories.
2) Add a new category. Save, close the directory.
3) Repeat steps 1 and 2.

Or
1) Create a document card.
2) Create a document card of another type.
3) Open the card created in step 1.

How many actions should contain one item? A question that all testers answer differently.
I believe that the total number of points should be no more than 5-6, the subsequent points are already perceived more difficult, the first advantage is lost.
One item must contain a set of actions that allows you to reach a certain point. Such a point could be the emergence of a system message, the creation of some artifact in the system - everything on which to pause playback.

9. Unambiguity

Our speech is rich in synonymous words and phrases, some of them are relevant and understandable to all, others - not very. I adhere to the following three principles.
The first principle is to avoid jargon and blurry words.

Example :
Bad - “the system swears”, “to click into the milk”, “the window is leaving for the screen”, “cantselnut”.
Good - “an unhandled exception is thrown”, “click into an empty window”, “the window moves off the screen”, “cancel”.

The second is to use the words in your team. The second principle can sometimes exclude the first. For example, if all the polls in a company say “zadizeybleno” instead of “inactive”, then the use of this word will be more understandable to the rest of the team. Nobody goes to the store for a battery, everyone goes for batteries.

Important! If different colleagues speak differently (someone “hint”, someone “hint”), for the effectiveness of further search for such an error, it is better to use both words in the description.

The third is one of the rules proclaimed in the film “The Initiate” - “Use the words correctly”. For example, sometimes the word “character” replaces the word “letter”, but these are different input data; they should not be confused.

10. Reread

After you have written and corrected the error description, be sure to re-read from the beginning to the end. Perhaps you will find a typo, inadvertently repeating a word, an extra character, or something like that. Since the view is blurred from reading my own text, I use the method of switching attention - I take my eyes literally a couple of seconds to a potted plant or a neighbor to the left, and then return to the text.

Additionally, I advise you to read Lee Lefevere 's book , The Art of Explaining . How to make you understand at a half-word. "

Learn to communicate your thoughts intelligently and clearly, so that you are easy and pleasant to read. And may the force be with you!

PS: The killer is a butler, and that “incredible piece of text” from the beginning of the article should have looked like this:

“The full file names in the file control of the document if there are several files do not fit.
1) Create any document UD. Leave in window mode, do not go to fullscreen.
2) Add more than 1 file on the Registration tab to the file control (context menu command or drag and drop).

Result: The file names are not fully visible. There is not enough space to display file names at the default window size.
Expected result: File names should be displayed in full. ”