DEV Community

Cover image for How to Write a Good Issue: Tips for Effective Communication in Open Source

How to Write a Good Issue: Tips for Effective Communication in Open Source

BekahHW on May 10, 2023

Three years ago I maintained my first open source project for Hacktoberfest. As a first-time maintainer, I underestimated the time and effort it wo...
Collapse
 
_eduard26 profile image
Eduard Constantin

:O you can inputs in the issue form?

Collapse
 
bekahhw profile image
BekahHW

Yep! I think this post links to how to do that and some examples.

Collapse
 
_eduard26 profile image
Eduard Constantin

Awesome! Thank you! With this I can make issues and PRs way easier to complete.

Collapse
 
gerimate profile image
Geri Máté

We've been trying to gain traction for our issues on GitHub. Following these tips might increase the appeal to them, thanks!

Collapse
 
bekahhw profile image
BekahHW

I hope they do! Let me know if it works out.

Collapse
 
hendrikras profile image
Hendrik Ras

The artwork used in this article is awesome, where did you get it?

Collapse
 
bekahhw profile image
BekahHW

The image at the top was generated from midjourney!

Collapse
 
hendrikras profile image
Hendrik Ras

Great prompting! I never seem to be able to get that kind of quality when dealing with AI. Or perhaps Im just impatient.

Thread Thread
 
bekahhw profile image
BekahHW

Here's the prompt I used: a girl writing a detailed note with circuit imagery behind her, neon colours, studio ghibli. Hayao Miyazki --v 5 --ar 100:42

Collapse
 
iamhectorsosa profile image
Hector Sosa • Edited

Great share! Framing some of these screenshots would've been chef's kiss! @bekahhw I've built a simple OSS tool for creating engaging screenshots with ease. Check it out and let me know what you think! Cheers!

github.com/ekqt/screenshot

Collapse
 
blkelly profile image
B Kelly

This is an extremely light version of what it takes to write an issue. Missing are things like severity, versioning of program under test, versioning of OS or browser, etc.
There are areas that should be selected when writing an issue, things like UI/UX, etc. and much more, so when the Dev team reviews the issue they know where it is and how to repeat it. Example: a large printer company I was testing install software for had extreme concerns for logo and naming. Colors and the visual aspect had to be 100% correct but a small error in spelling was something low on the totem pole, but still needed to be done eventually.
Step by step instructions must always be included.
Testing is saturated with wrong ideals of testing and what it actually takes to perform excellent testing.
There was a local mid level manager that told a local college she could create qualified testers with a two day a week six week course. I almost wet my pants laughing so hard when the head of that college's adult courses told me. Some manages have even said it's something monkeys could do. Of course the product they are covering is usually over budget, over the scheduled release date and bad!
I think I may add some content in the future.
Thanks

Collapse
 
bekahhw profile image
BekahHW

That’s a great example. Thanks for sharing!