4 minutes
Writing an effective issue report | Guide to go from “its not working” to a usable report
It is very important to understand how to write a proper issue report. In the moment when we are facing a issue and do not understand how it can be resolved, we forget that the person who we are asking the issue does not have any idea and is hearing about the issue first time from you. we need to make sure they are properly given context of the issue.
Creating an effective issue report takes at least a little work as we find most of the things in life. The more effort you put it the quicker you get the result.
It is good to understand following things before you raise a request:
Do not ask question in one sentence.
This does not give any information about your issue whatsoever.
"I need help with nginx"
vs
"I need help setting up my nginx server to work as reverse proxy for my nodeJS application"
Don’t assume
We should not assume that person trying to help you knows anything about the thing you’re having a problem with. Give them more context
"I cannot ping my server"
vs
"I cannot ping my server at this domain which should be at this ip address"
Identify what exactly is going wrong.
"Somethng is not working"
vs
"I am having issue accessing this website when i access this website. It is giving me an error page at https://somebrokenwebsite.com/broken"
What are you trying to achieve
Clearly explain what you want to do what how you came into this issue. This provides good context of the problem.
What did you do to troubleshoot
Explain what steps you did to come to the conclusion that something is not working or borked. This may be
"I tried to access it via web"
"Searched on SO and did not find proper solution"
"Checked the logs but could not intrepret what went wrong"
Provide any additional
Try to provide any information which could help in investigating which can be code snippet, screenshot, logs, output messages etc. Sometime a screenshot or video capture are worths 1000 words.
Be precise
Writing issue report is not an essay, be precise, specific and thorough. Always provide the necessary and sufficient information.
Make sure you use correct pronouns
"I was trying to access it and it failed to respond"
What “it” means this the above sentence
Template
Here is a template that you can follow while raising an issue report.
Hello,
I am having an issue. Could anyone help me resolve/debug this
What happened ( the actual behaviour) ?
What was changed ?
Walk me through exactly what you did from beginning to end ( steps to reproduce) ?
Things i did to troubleshoot and What error message and error code is displayed?
Screengrabs or Logs or Outputs ?
Demo issue report
Here is an example of a issue report:
Hello,
I am having an issue deploying my python app in netlify. Could you please help me
I am not able to access my flask app deployed in netlify.
When i do a git commit, netlify should have picked it up and deployed the app and i should have been able to access it via this domain.
I had configured netlify to point to my custom DNS.
I tried hooking my GitHub repo which consists of the flask app to notify which seems to be fine as netlify can reach out and pull my code as I make any change.
I also configured the base command which needs to be running to start the flask app on netlify UI.
Deployment seems to be working fine as it shows green in the deployment ( shown in screenshot )
When I do a curl, I get 503 error ( as shown in the screenshot)
Accessing the web gives error page
I cannot ping the server domain and IP address.
here are the screenshots of the things mentioned above, and the code output from the error.
Regards,
Prabesh
I hope this information was useful and i am sure this will make your life much easier by resolving any issue you are having quickly. Please share it with your friends who needs it.