You’d think in 2025, people would know how to give feedback on open source projects without coming off like a discount Gordon Ramsay with a GitHub account.
Spoiler: they don’t.
I recently had an encounter with a reviewer who, in his infinite wisdom, decided to open a GitHub issue declaring, and I quote:
“No docs, screenshots, examples or demos.”
That was it. No “Hi”, no context, not even a “thanks for sharing your work” before swinging the wrecking ball through my project’s front door.
The kicker?
Our documentation was right there, linked in the README, complete with a content tree that even worked with JavaScript disabled. All he had to do was… scroll.
When I pointed this out (politely at first, then less so), the response I got was… well… something:
“First, entirely my bad. I did click on Get Started, but somehow I missed that there was anything more than the first page… Maybe because I was very short on sleep… I was not trying to be sarcastic or introduce HN drama…”
So basically: It’s your fault I didn’t read, but also I was sleepy, so you see, it’s not really my fault.
Classic.
The Actual Point Here
This isn’t about one guy. It’s about a mindset.
If you’re going to review an open source project:
-
Check twice, post once
Make sure your complaint is actually true. Scroll. Click. Read. Heck, open DevTools if you have to. -
Lead with curiosity, not a conclusion
Instead of “No docs”, try “Hey, I couldn’t find the docs—are they somewhere else?” Same feedback, zero passive-aggressive energy. -
Remember there’s a human on the other side
Someone spent evenings, weekends, and caffeine money building that thing you’re picking apart. Treat them like you would if you were in the same room. -
If you messed up, actually apologise
“My bad” is fine for spilling coffee. For wasting someone’s time, try:“I’m sorry, I didn’t see that. My mistake.”
Not complicated.
Why It Matters
Open source is fragile. It runs on goodwill, volunteer hours, and the masochistic joy of solving problems for strangers.
When feedback turns into cheap shots, maintainers burn out faster than you can say “npm uninstall”.
Be direct. Be honest. But don’t be that guy.
We all know a “that” guy. Let’s not add to the population.
P.S. The GitHub issue? Archived. Life’s too short for bad vibes.
P.P.S. If you’re reading this from Hacker News: yes, I’m talking about you. Don’t pretend you didn’t click.