I've worked on a few large-scale OSS projects, and I believe that people find it easier to just leave a comment and rely on a contributor to explain a problem rather than consulting the documentation. I consider doing everything you can to make people find their own answers a strong part of defensive open source.
For the posts I write, I have an even lower tolerance for comments. For example, I added the ability to turn off comments per-post and haven't allowed comments on any posts I've written here. A lot of transitory discussion around an article happens on twitter via @ArtsyOpenSource.
I'm willing to give it another shot though, and so I got around to creating a simple system for allowing opt-in comments on posts using GitHub Issues. The rest of this post will be about how you can do it also, and a bit about why I think GitHub Issues are a happy medium for the comments.
Getting set up
I've worked around this with a project called gh-commentify, a node app whose job is to wrap your comment API requests with an access token. You can create your own instance on heroku using this link. It gets scoped to a single org/user, so you can avoid others using your heroku instance for their blog.
From there you need to be able to declare in a post what issue it is hooked up to. This blog uses Jekyll, which has YAML Front Matter on posts. So, I edited our post templates to look for a key
From there you need to grab the comments JSON, and move them into the DOM.
I based my work on these two posts:
However this version is more reliable (GitHub authenticated requests) and has fewer dependencies (no jQuery for example).
1 2 3 4 5
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41
The style of our comments are built to evoke the GitHub UI for issues. This is done to prime people for a relatively different type of comment creation, but still feel like it's a part of the Artsy OSS style.
It's easier for you to keep track of the conversations, you're likely already having a lot of conversations in a place like GitHub. This means you can use the same flow and tools as your daily job, not relying on a third party service's emails.
You have good admin tools: you can edit comments, block and report problematic users. These are tools that you have for all repos.
People will be using their developer accounts, which I'd like to hope they will take pride in. You're probably more likely to get high quality responses. The lack of threading is a bit of a shame in this context, but we've lived with it in GitHub Issues for this long, so I'm OK with this.
This setup makes it trivial to drop comments from the blog anytime, and you still have all the comments around in a constructive way after. We don't have to hope that other services have export features and open data. Everything public is open data on GitHub.
So: low maintenance, works on static sites, data isn't silo-ed and it's more likely to result in positive interactions.