Community Engagement, Learning, & GitHub
If you’re a developer, there’s a good chance you’ve seen the image above, and laughed suavely under your breath.
Foolish user, expecting user support on a developer forum.
Unfortunately, the comments on this post share a similar sentiment, complaining that if the user “doesn’t know what they’re doing, they shouldn’t be using GitHub.”
Motivation
This general consensus always seemed weird to me.
Let me be clear, big important projects with big important teams have better things to do than to help little Timmy setup Visual C++ toolchain on his toaster. I don’t need Linus Torvalds gently caressing my hand as he guides me through installing Hannah Montana Linux on my 2004 Dell Inspiron.
But why is the default approach to tell users to “go away” instead of “let me help you understand?”
Community Support
Raise your hand if you’ve ever seen a post on Reddit like this:
I’m new to X, and I want to achieve Y. Can someone point me in the right direction?
And the top comment is:
Read the docs. (link to docs, no further explanation)
—or:
*Sarcastic LMGTFY link*
—or even better:
Hey, are you aware of this wonderful tool called Google? It’s a search engine that can help you find answers to your questions. You should try it sometime.
This geniunely floors me. Like dude, what if your boss walked in and asked you to explain what a monad is? Would you say:
- “RTFM, bozo”
- “A monad is a monoid in the category of endofunctors”
- Actually get up and start a meaningful conversation
Seriously! If the person in question wasn’t looking for specialized help, they certainly would not have come to the den of neckbeards for answers.
Who’s to Blame?
Well, I would say GitHub has actually done a really darn good job at attempting to make their platform accessible to everyone (for FREE, mind you). We have features like deployments, actions, and more recently, discussions.
All of these features do one of two things:
- Make it easier for developers to showcase/distribute their work
- Facilitate the meta-discussion around the project
The sad truth is, most developers don’t know how to use these features, or simply can’t be assed to used them.
I’m going to briefly touch on the above features, and how they can vastly improve the accessibility of your project.
Community Engagement in Small Projects
If you’ve ever lead a successful full-stack open-source project (unlikely), you might have experienced the raw power that comes from making your users work for you.
Haha, yes, fix my typos, you peasants!
Seriously, if non-technical users are willing to sign up to GitHub to tell you that your stuff’s broken, you absolutely cannot take that for granted.
Welcoming Issues & Feature Requests
If you read what I just wrote, then this should be self explanatory. Any info is better than none, especially if “none” means “no feedback whatsoever”.
Put a big button or link somewhere on your app or website that says “Report an Issue”. A GitHub icon does not mean anything to anyone who doesn’t already have better things to do with their time. (sad but true)
Stop Closing Issues like Your Life Depends on It
If I find out two separate issues are somehow related in-code, I don’t bother closing the first one.
First off, it’s actually more work to close the issue. If you just leave both open, you can reference the other issue in the comments, and call it a day.
Second, once the bug is fixed, check back on both issues. That way you can make sure both users are happy, rather than saying “erm, actually I don’t care about you, user #2. Marking as duplicate.”
AI Issue Triage
I think many of us sleep on the usefulness of AI GitHub helper platforms. Some I’ve tried are CodeRabbit and Dosu. These are free for open-source projects, and can seriously be your wingman, especially if you are a solo developer.
For one of my projects, a Stardew Valley save-editor tool, I simply linked the SDV modding Wiki, and instructed it “not to expect users to be coders”. This is enough for it to help disgrunted users with basic troubleshooting, reference existing issues, reference info about the game itself, and (most importantly) save my critical-thinking-juices by finding culprit commits/code.
Collaboration
Merit has always seemed to be an under-appreciated aspect of the open-source community. If you’re a developer, you’ve probably wasted a Saturday afternoon debuging an issue in an open-source library, and writing a PR to fix it, just for the maintainer to copy & paste your code into their own commit, and close your PR.
Does it matter? Not really, you got the fix you needed, right? Does it feel good? No, of course not. (I’m looking at you [redacted] from cloudflare/workerd)
The Point
On the off-chance that someone does contribute to your back-alley project, you should give them credit. Personally, I don’t stop at code; if someone saves me time, or does literally any research whatsoever, I’ll happily credit them.
Why? Because I want them to do it again. Again, and again, and again—and again. I want all the little people in my monitor to keep finding bugs for me. I want them to keep fixing my typos. I want them to keep making my project better.
The Solution
Conveniently, as an author, there is a really good solution to solving achieve this (when merging a PR isn’t applicable). When creating a git commit, simply add the following line to the end of your commit message:
Co-authored-by: username <[email protected]>“But Cole,” I hear you say, “what if I don’t have their email address?” That’s a great question. In fact, by default, GitHub hides your email address on your profile. So if this is one of those “I made an account just to report this issue” type users, then you’re out of luck.
Sike! Let me bless your minds with some archaic knowledge that I dredged up from the depths of the GitHub docs, with the help of the all-knowing hermit, Claude 3.5:
Co-authored-by: Xx_MergeM4st3r69_xX <[email protected]>That’s all you need, and GitHub will automatically link the user to the commit, and give them credit for their contribution.
Issue Templates
This one is a no-brainer. If you’re not using issue templates, you’re doing it wrong. The first thing anyone should see when they click the “New Issue” button is a list of options, containing the exact situation the user has found themselves in.
I’m not talking just “bug” and “help”. You must roleplay as a Chimpanzee with a learning disability, and walk through each “user story”, and find each type of misery that could befall you.
I’ve made save-editor project (mentioned above), I’ve created “File Upload Errors” and “Interface Errors”, “Game Crashes”, etc.
Again, let the user do the work for you.
Actions
There’s virtually no excuse to not be using GitHub Actions somewhere in your project. CI and CD are a bonus, but think bigger. It doesn’t matter if this is a library/package, a web app, or a CLI tool; you can deploy builds, build artifacts, and upload package releases with Actions. There are literally GitHub Actions to create macOS installer images.
GitHub’s Dark Design Patterns
Look at this photograph. What do you see?
On the left, there is a monotonous table of files, all in grey monotone colours. On the right, there are big headings, colourful links and relevant tags, flavourful icons, a bunch of bright profile pictures, and… well, would you look at that? Releases and Packages!
GitHub is guiding users to the most important parts of the project. When a user lands on your project, they should be able to see at least one of the following:
- A file to download
- A package to install
- A relevant URL to visit
H-hold a just minute! Did you just say– *checks notes* a file?? To download?!?!?
That’s right, buster! You can go kick dirt, because even GitHub knows that we’re all deluding ourselves with delusions of “pip install” and “JavaScript package managers”.
The unfortunate fact is that if you go to any popular project on GitHub, you won’t see any of this. You’ll see a README, a LICENSE, and a CONTRIBUTING file. That’s it. No releases, no packages, no links. 😔
Conclusion
Knowledge is power, but absolute power corrupts absolutely. I think some of us could learn to be a little more patient, and spend a bit more time building our resources, rather than just our code.