No edit summary |
No edit summary |
||
| (6 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
==How to write a Bug report== | |||
==Introduction== | ===Introduction=== | ||
On this Wiki-page I'll try to explain how you can write a good bug report. | On this Wiki-page I'll try to explain how you can write a good bug report. | ||
The aim of a bug report is to enable the programmer to see the program failing in front of them. You should give them careful and detailed instructions on how to make it fail. If they can reproduce the error, they will try to get as much information until they know the cause. If they can’t reproduce the error, you need to get that information for them. | The aim of a bug report is to enable the programmer to see the program failing in front of them. You should give them careful and detailed instructions on how to make it fail. If they can reproduce the error, they will try to get as much information until they know the cause. If they can’t reproduce the error, you need to get that information for them. | ||
==State the facts…== | ===State the facts…=== | ||
In a bug report you should try to state clear facts what was happening to you when you used | In a bug report you should try to state clear facts what was happening to you when you used | ||
| Line 13: | Line 13: | ||
If you have some speculations what might have happened you can include that but if you aren't sure about it just leave it out, it may cause more confusion than necessary. | If you have some speculations what might have happened you can include that but if you aren't sure about it just leave it out, it may cause more confusion than necessary. | ||
==Be Nice…== | ===Be Nice…=== | ||
When you're writing the report you should write it in a friendly and polite form, it wont help if you insult them or anything in that direction. They may have programmed/developed it but they don't want it too fail when you're using it. | When you're writing the report you should write it in a friendly and polite form, it wont help if you insult them or anything in that direction. They may have programmed/developed it but they don't want it too fail when you're using it. | ||
==You cant just write “It doesn't work”…== | ===You cant just write “It doesn't work”…=== | ||
Like i said above they don't want you to fail while using the program, since they haven't noticed the potential bug the program was running fine for them in their setup. | Like i said above they don't want you to fail while using the program, since they haven't noticed the potential bug the program was running fine for them in their setup. | ||
| Line 26: | Line 26: | ||
What Version/distribution of the Program/Software do you have | What Version/distribution of the Program/Software do you have | ||
==Asking for general help…== | ===Asking for general help…=== | ||
If you are just asking for help and don't want to report a bug, you should tell the programmer where you already looked for information. They may can use this information to make they're own documentation better. | If you are just asking for help and don't want to report a bug, you should tell the programmer where you already looked for information. They may can use this information to make they're own documentation better. | ||
==Show it…== | ===Show it…=== | ||
The best way to report the bug is to show it to the programmer since for example Mr. Hasler cant be here in Person every time you need to figure out another effective way to show them. They need to see how you start the PC, run the Software, see how you interact with it and how the Software responses. This step is very important so that they can try to reproduce the bug by themselves in order to fix it. | The best way to report the bug is to show it to the programmer since for example Mr. Hasler cant be here in Person every time you need to figure out another effective way to show them. They need to see how you start the PC, run the Software, see how you interact with it and how the Software responses. This step is very important so that they can try to reproduce the bug by themselves in order to fix it. | ||
| Line 54: | Line 54: | ||
send them the specs of the other on too | send them the specs of the other on too | ||
==Works for them but not for you…== | ===Works for them but not for you…=== | ||
If the programmer recreated your commands/inputs/actions/… and it works for them you may haven't given them enough information. Maybe the error doesn't appear on every Computer. | If the programmer recreated your commands/inputs/actions/… and it works for them you may haven't given them enough information. Maybe the error doesn't appear on every Computer. | ||
| Line 71: | Line 71: | ||
At this point the programmer still wants to reproduce your failure, they need to know what and where it has gone wrong. Write the errors down message and number are equally important, even if the computer cant give you out the information in words theres still important information in numbers or signs he's outputting. | At this point the programmer still wants to reproduce your failure, they need to know what and where it has gone wrong. Write the errors down message and number are equally important, even if the computer cant give you out the information in words theres still important information in numbers or signs he's outputting. | ||
==And then i tried this to solve the Problem…== | ===And then i tried this to solve the Problem…=== | ||
You probably have done some things after the bug showed up too you to fix it yourself, these action may have made things worse or changed something the programmer cant easily reproduce. Try to remember what you did afterwards and also give detailed information about that. | You probably have done some things after the bug showed up too you to fix it yourself, these action may have made things worse or changed something the programmer cant easily reproduce. Try to remember what you did afterwards and also give detailed information about that. | ||
If you're not sure what you're doing, don't do anything after the bug shows up you will make it worse! | If you're not sure what you're doing, don't do anything after the bug shows up you will make it worse! | ||
| Line 83: | Line 83: | ||
==Sometimes it works…== | ===Sometimes it works…=== | ||
If you're confronted with a bug that just occurs from time to time try to search for a pattern in it. Try different setups several times and write down how many times the bug occurred and what differs to the times it was working. | If you're confronted with a bug that just occurs from time to time try to search for a pattern in it. Try different setups several times and write down how many times the bug occurred and what differs to the times it was working. | ||
| Line 102: | Line 102: | ||
==Be specific no matter you're writing in english or german…== | ===Be specific no matter you're writing in english or german…=== | ||
Don't just tell them i loaded that file into it, tell them how you loaded it by pressing keys, typing a command line or using graphical buttons. This can matter too. Write more than they actually need to know they're willing to ignore the information that isn't needed over getting to less information. | Don't just tell them i loaded that file into it, tell them how you loaded it by pressing keys, typing a command line or using graphical buttons. This can matter too. Write more than they actually need to know they're willing to ignore the information that isn't needed over getting to less information. | ||
| Line 111: | Line 111: | ||
==Asking for general help…== | ===Asking for general help…=== | ||
If you are just asking for help and don't want to report a bug, you should tell the programmer where you already looked for information. They may can use this information to make they're own documentation better. | If you are just asking for help and don't want to report a bug, you should tell the programmer where you already looked for information. They may can use this information to make they're own documentation better. | ||
==Summary== | ===Summary=== | ||
1. Let the programmer see what you've seen | 1. Let the programmer see what you've seen | ||
| Line 138: | Line 138: | ||
11. Be sure you're description cant be misinterpreted | 11. Be sure you're description cant be misinterpreted | ||
==Performance Platform Specific== | ===Performance Platform Specific=== | ||
You can reach the team of Captury via mail or by calling them: | You can reach the team of Captury via mail or by calling them: | ||
Nils Hasler hasler@thecaptury.com | |||
Nils Hasler: | |||
hasler@thecaptury.com | |||
Tel.: +49 681 302-64931 | Tel.: +49 681 302-64931 | ||
Latest revision as of 18:25, 30 July 2016
How to write a Bug report
Introduction
On this Wiki-page I'll try to explain how you can write a good bug report. The aim of a bug report is to enable the programmer to see the program failing in front of them. You should give them careful and detailed instructions on how to make it fail. If they can reproduce the error, they will try to get as much information until they know the cause. If they can’t reproduce the error, you need to get that information for them.
State the facts…
In a bug report you should try to state clear facts what was happening to you when you used the program. Example: I was using the program to do this but this happened. If you have some speculations what might have happened you can include that but if you aren't sure about it just leave it out, it may cause more confusion than necessary.
Be Nice…
When you're writing the report you should write it in a friendly and polite form, it wont help if you insult them or anything in that direction. They may have programmed/developed it but they don't want it too fail when you're using it.
You cant just write “It doesn't work”…
Like i said above they don't want you to fail while using the program, since they haven't noticed the potential bug the program was running fine for them in their setup. So that in mind give them detailed information on how your setup is like cause its most likely different from the one they have. More clear information is always better then less. On What System are you running the Software What are the specs of your PC What Version/distribution of the Program/Software do you have
Asking for general help…
If you are just asking for help and don't want to report a bug, you should tell the programmer where you already looked for information. They may can use this information to make they're own documentation better.
Show it…
The best way to report the bug is to show it to the programmer since for example Mr. Hasler cant be here in Person every time you need to figure out another effective way to show them. They need to see how you start the PC, run the Software, see how you interact with it and how the Software responses. This step is very important so that they can try to reproduce the bug by themselves in order to fix it.
There are several possibilities:
1. You can make a screen video of you reproducing the bug
2. You can make screen shots and write information into them
3. Write a detailed description of every click you made since you started the PC
4. You could ask them to make a Skype or Teamviewer session with you to share your screen live
5. If you weren't precise enough do it over again as they wish, or try some variations to get to the same point were you actually wanted to be.
6. If its a graphical problem you're confronted with tell them exactly in wich order you pressed the buttons, if its a problem writing commands they need to know exactly what commands you typed and what the computer outputted as response.
7. If you're loading the data from a specific file you created send them over to them.
8. If you're using the program to talk to another via Network Computer you also need to send them the specs of the other on too
Works for them but not for you…
If the programmer recreated your commands/inputs/actions/… and it works for them you may haven't given them enough information. Maybe the error doesn't appear on every Computer. Or you have got it wrong what the program is should do and is able too, so it maybe that you got it right but for your opinion its turning out wrong.
1. Provide the information of what your intention was by using the program.
2. Tell them what exactly happened
3. Tell them what you thought it should happen
4. Tell them exactly what Error message you saw
5. Are there unexplainable delays and when
At this point the programmer still wants to reproduce your failure, they need to know what and where it has gone wrong. Write the errors down message and number are equally important, even if the computer cant give you out the information in words theres still important information in numbers or signs he's outputting.
And then i tried this to solve the Problem…
You probably have done some things after the bug showed up too you to fix it yourself, these action may have made things worse or changed something the programmer cant easily reproduce. Try to remember what you did afterwards and also give detailed information about that. If you're not sure what you're doing, don't do anything after the bug shows up you will make it worse! When something goes wrong, immediately stop doing anything. Don't touch any buttons at all. Just look at the screen and try to write down everything that isn't ordinary. The only things you can do by yourself is closing the program or rebooting the computer. Even if you're good at programming don't try to do things you don't know anything about, you aren't the person who has written the code so you can never be a hundred percent sure of anything what the company actually there. You describe the symptoms, don't assume a diagnosis it will only lead to general confusion. Even if you think the commands/changes etc. the programmer provides you with will not work cause you know it better, still try it there will be some reason he wants you to try that.
Sometimes it works…
If you're confronted with a bug that just occurs from time to time try to search for a pattern in it. Try different setups several times and write down how many times the bug occurred and what differs to the times it was working.
1. Where you using an extra large file
2. Did some other program access the file at the same time
3. Are you running any other programs you weren't running the last time
4. Do you use another display or beamer then before
5. Maybe you're just stressed cause of a deadline and weren't using the software carefully enough.
6. What version of the program you are using with wich version of your operating system
Be specific no matter you're writing in english or german…
Don't just tell them i loaded that file into it, tell them how you loaded it by pressing keys, typing a command line or using graphical buttons. This can matter too. Write more than they actually need to know they're willing to ignore the information that isn't needed over getting to less information. If you write them to less information they need to come/mail back to you and ask you those things and the process will therefore take longer as giving them a good specific description in the first place. Dont use “it”: I used it then it opened a file and then it crashed. What did crash here, the opening of the file or the whole program. You also need to be careful while using pronouns, the programmer cant see into your setup unless he's standing right behind you. Read what you've written before you send it off to the programmer, go through your own steps and recreate the situation while using you're instructions as a guideline. Thats the best way to assume that the programmer will get to the same situation as you did.
Asking for general help…
If you are just asking for help and don't want to report a bug, you should tell the programmer where you already looked for information. They may can use this information to make they're own documentation better.
Summary
1. Let the programmer see what you've seen
2. If they cant see it failing themselves describe what went wrong
3. Describe everything in Detail
4. Tell them what you saw and what you were expecting to see
5. Write down the Error messages
6. When something unexpected happens leave the Situation like that until you're calm
7. Describe the symptoms don't make a diagnosis
8. Provide the programmer with any extra information he needs
9. Tell them you're version numbers
10. Be specific and write in clear language
11. Be sure you're description cant be misinterpreted
Performance Platform Specific
You can reach the team of Captury via mail or by calling them:
Nils Hasler:
hasler@thecaptury.com
Tel.: +49 681 302-64931