Enabling two way communication with WordPress and GitHub for Issues

Enabling two way communication with WordPress and GitHub for Issues

This week, using the magic of open web standards, I was able to write an issue post on my own website, automatically syndicate a copy of it to GitHub, and later automatically receive a reply to the copy on GitHub back to my original post as a comment there. This gives my personal website a means of doing two way communication with GitHub.

This functionality is another in a long line of content types my website is able to support so that I’m able to own my own content, yet still be able to interact with people on other websites and social media services. Given the number of social sites I’ve seen disappear over the years (often taking my content with them), this functionality gives me a tremendously larger amount of control and ownership over my web presence and identity while still allowing me to easily communicate with others.

In this post I wanted to briefly sketch what I’ve done to enable this functionality, so others who are so inclined can follow along to do the same thing.

Setting up WordPress to syndicate to GitHub

I’ll presume as a first step that one has both a GitHub account and a self-hosted WordPress website, though the details will also broadly apply to just about any content management system out there that supports the web standards mentioned.

Register your GitHub account and your website with Bridgy

Ryan Barrett runs a fantastic free open sourced service called Bridgy. To use it you’ll need the microformat rel=​​​“me” links on both your GitHub account and your website’s homepage that point at each other.  GitHub will do most of the work on its side for you simply by adding the URL of your website to the URL field for your GitHub account at https://github.com/settings/profile. Next on your website’s homepage, you’ll want to add a corresponding rel=​​​​​“me” link from your website to your GitHub account.

In my case, I have a simple widget on my homepage with roughly the following link:
<a href="https://github.com/username">GitHub</a>
in which I’ve replaced ‘username’ with my own GitHub username. There are a variety of other ways to add a rel=​​​​​“me” link to your webpage, some of which are documented on the IndieWeb wiki.

Now you can go to Brid.gy and under “Connect your accounts” click on the GitHub button. This will prompt you to sign into GitHub via oAuth if you’re not already logged into the site. If you are already signed in, Brid.gy will check that the rel=​​​​​“me” links on both your site and your GitHub account reciprocally point at each other and allow you to begin using the service to pull replies to your posts on GitHub back to your website.

To allow Brid.gy to publish to GitHub on your behalf (via webmention, which we’ll set up shortly), click on the “Publish” button.

Install the Webmention Plugin

The underlying technology that allows the Bridgy service to both publish on one’s behalf as well as for the replies from GitHub to come back to one’s site is an open web standard known as Webmention. WordPress can quickly and easily support this standard with the simple Webmention plugin that can be downloaded and activated on one’s site without any additional configuration.

For replies coming back from GitHub to one’s site it’s also recommended that one also install and activate the Semantic Linkbacks Plugin which also doesn’t require any configuration. This plugin provides better integration and UI features in the comments section of one’s website.

Install Post Kinds Plugin

The Post Kinds Plugin is somewhat similar to WordPress’s Post Formats core functionality, it just goes the extra mile to support a broader array of post types with the appropriate meta data and semantic markup for interacting with Bridgy, other web parsers, and readers.

Download the plugin, activate it, and in the plugin’s settings page enable the “Issue” kind. For more details on using it, I’ve written about this plugin in relative detail in the past.

Install Bridgy Publish Plugin

One can just as easily install the Bridgy Publish Plugin for WordPress and activate it. This will add a meta box to one’s publishing dashboard that, after a quick configuration of which social media silos one wishes to support, will allow one to click a quick checkbox to automatically syndicate their posts.

Install the Syndication Links Plugin

The Syndication Links plugin is also a quick install and activate process. You can modify the settings to allow a variety of ways to display your syndication links (or not) on your website if you wish.

This plugin will provide the Bridgy Publish Plugin a place to indicate the permalink of where your syndicated content lives on GitHub. The Bridgy service will use this permalink to match up the original content on your website and the copy on GitHub so that when there are replies, it will know which post to send those replies to as comments which will then live on your own website.

Post away

You should now be ready to write your first issue on your website, cross post it to GitHub (a process known in IndieWeb parlance as POSSE), and receive any replies to your GitHub issue as comments back to your own website.

Create a new post.

In the “Kinds” meta box, choose the “Issue” option.

Screen capture of the Kinds meta box with "Issue" option chosen.
Kinds meta box with “Issue” option chosen.

Type in a title for the issue in the “Title” field.

In the “Response Properties” meta box, put the permalink URL of the Github repopository for which you’re creating an issue. The plugin should automatically process the URL and import the repository name and details.

The “Response Properties” meta box.

In the primary editor, type up any details for the issue as you would on GitHub in their comment box. You can include a relatively wide variety of custom symbols and raw html including

and  with code samples which will cross-post and render properly.

In the GitHub meta box, select the GitHub option. You can optionally select other boxes if you’re also syndicating your content to other services as well. See the documentation for Bridgy and the plugin for how to do this.

Screen capture of the Bridgy Publish meta box with GitHub chosen
Bridgy Publish meta box with GitHub chosen.

Optionally set any additional metadata for your post (tags, categories, etc.) as necessary.

Publish your post.

On publication, your issue should be automatically filed to the issue queue of the appropriate GitHub repo and include a link back to your original (if selected). Your post should receive the syndicated permalink of the issue on GitHub and be displayed (depending on your settings) at the bottom of your post.

Syndication Links Plugin will display the location of your syndicated copies at the bottom of your post.

When Bridgy detects future interactions with the copy of your post on GitHub, it will copy them and send them to your original post as a webmention so that they can be displayed as comments there.

An example of a comment sent via webmention from GitHub via Brid.gy. It includes a permalink to the comment as well as a link to the GitHub user’s profile and their avatar.

If you frequently create issues on GitHub like this you might want a slightly faster way of posting. Toward that end, I’ve previously sketched out how to create browser bookmarklets that will allow you one click post creation from a particular GitHub repo to speed things along. Be sure to change the base URL of your website and include the correct bookmarklet type of “issue” in the code.

The Post Kinds plugin will also conveniently provide you with an archive of all your past Issue posts at the URL http://example.com/kind/issue/, where you can replace example.com with your own website. Adding feed/ to the end of that URL provides an RSS feed link as well. Post Kinds will also let you choose the “Reply” option instead of “Issue” to create and own your own replies to GitHub issues while still syndicating them in a similar manner and receive replies back.

Other options

Given the general set up of the variety of IndieWeb-based tools, there are a multitude of other ways one can also accomplish this workflow (both on WordPress as well as with an infinity of other CMSes). The outline I’ve provided here is one of the quickest methods for beginners that will allow a relatively high level of automation and almost no manual work.

One doesn’t necessarily need to use the Post Kinds Plugin, but could manually insert all the requisite HTML into their post editor to accomplish the post side of things via webmention. (One also has the option to manually syndicate the content to GitHub by cutting and pasting it as well.) If doing things manually this way is desired, then one will need to also manually provide a link to the syndicated post on GitHub into their original so that Bridgy can match up the copy and the original to send the replies via webmention.

More details on how to use Bridgy with Github manually in conjunction with WordPress or other CMSes can be found here: https://brid.gy/about#github-issue-comment

Further steps

If you’ve followed many of these broad steps, you’ve given already given yourself an incredibly strong IndieWeb-based WordPress installation. With a minimal amount of small modifications you can also use it to dovetail your website with other social services like Twitter, Facebook, Flickr, Instagram, Google+ and many others. Why not take a quick look around on the IndieWeb wiki to see what other magic you can perform with your website!

I’ve documented many of my experiments, including this one, in a collection of posts for reference.

Help

If you have questions or problems, feel free to comment below or via webmention using your own website. You can also find a broad array of help with these plugins, services, and many other pieces of IndieWeb technology in their online chat rooms.​​​​​​​​

Enabling two way communication with WordPress and GitHub for Issues was originally published on Chris Aldrich

Advertisements

Buzzfeed implements the IndieWeb concept of backfeed to limit filter bubbles

Outside Your Bubble

This past Wednesday, BuzzFeed rolled out a new feature on their website called “Outside your Bubble”. I think the concept is so well-described and so laudable from a journalistic perspective, that I’ll excerpt their editor-in-chief’s entire description of the feature below. In short, they’ll be featuring some of the commentary on their pieces by pulling it in from social media silos.

What is interesting is that this isn’t a new concept and even more intriguing, there’s some great off-the-shelf technology that helps people move towards doing this type of functionality already.

The IndieWeb and backfeed

For the past several years, there’s been a growing movement on the the internet known as the IndieWeb, a “people-focused alternative to the ‘corporate web’.” Their primary goal is for people to better control their online identities by owning their own domain and the content they put on it while also allowing them to be better connected.

As part of the movement, users can more easily post their content on their own site and syndicate it elsewhere (a process known by the acronym POSSE). Many of these social media sites allow for increased distribution, but they also have the side effect of cordoning off or siloing the conversation. As a result many IndieWeb proponents backfeed the comments, likes, and other interactions on their syndicated content back to their original post.

Backfeed is the process of pulling back interactions on your syndicated content back (AKA reverse syndicating) to your original posts.

This concept of backfeed is exactly what BuzzFeed is proposing, but with a more editorial slant meant to provide additional thought and analysis on their original piece. In some sense, from a journalistic perspective, it also seems like an evolutionary step towards making traditional comments have more value to the casual reader. Instead of a simple chronological list of comments which may or may not have any value, they’re also using the feature to surface the more valuable comments which appear on their pieces. In a crowded journalistic marketplace, which is often misguided by market metrics like numbers of clicks, I have a feeling that more discerning readers will want this type of surfaced value if it’s done well. And discerning readers can bring their own value to a content publisher.

I find it interesting that not only is BuzzFeed using the concept of backfeed like this, but in Ben Smith’s piece, he eschews the typical verbiage ascribed to social media sites, namely the common phrase “walled garden,” in lieu of the word silo, which is also the word adopted by the IndieWeb movement to describe a “centralized web site typically owned by a for-profit corporation that stakes some claim to content contributed to it and restricts access in some way (has walls).”

To some extent, it almost appears that the BuzzFeed piece parrots back portions of the Why IndieWeb? page on the IndieWeb wiki.

Helping You See Outside Your Bubble | BuzzFeed

A new feature on some of our most widely shared articles.

BuzzFeed News is launching an experiment this week called “Outside Your Bubble,” an attempt to give our audience a glimpse at what’s happening outside their own social media spaces.

The Outside Your Bubble feature will appear as a module at the bottom of some widely shared news articles and will pull in what people are saying about the piece on Twitter, Facebook, Reddit, the web, and other platforms. It’s a response to the reality that often the same story will have two or three distinct and siloed conversations taking place around it on social media, where people talk to the like-minded without even being aware of other perspectives on the same reporting.

Our goal is to give readers a sense of these conversations around an article, and to add a kind of transparency that has been lost in the rise of social-media-driven filter bubbles. We view it in part as a way to amplify the work of BuzzFeed News reporters, and to add for readers a sense of the context in which news lives now.

And if you think there’s a relevant viewpoint we’re missing, you can contact the curator at bubble@buzzfeed.com.

Source: Helping You See Outside Your Bubble | Ben Smith for BuzzFeed

Editorial Perspective and Diminishing Returns

The big caveat on this type of journalistic functionality is that it may become a game of diminishing returns. When a new story comes out, most of the current ecosystem is geared too heavily towards freshness: which story is newest? It would be far richer if there were better canonical ways of indicating which articles were the most thorough, accurate, timely and interesting instead of just focusing on which was simply the most recent. Google News, as an example, might feature a breaking story for several hours, but thereafter every Tom, Dick, and Harry outlet on the planet will have their version of the story–often just a poorer quality rehash of the original without any new content–which somehow becomes the top of the heap because it’s the newest in the batch. Aram Zucker-Scharff mentioned this type of issue a few days ago in a tweetstorm which I touched upon last week.

Worse, for the feature to work well, it relies on the continuing compilation of responses, and the editorial effort required seems somewhat wasted in doing this as, over time, the audience for the article slowly diminishes. Thus for the largest portion of the audience there will be no commentary, all the while ever-dwindling incoming audiences get to see the richer content. This is just the opposite of the aphorism “the early bird gets the worm.” Even if the outlet compiled responses on a story from social media as they were writing in real time, it becomes a huge effort to stay current and capture eyeballs at scale. Hopefully the two effects will balance each other out creating an overall increase of value for both the publisher and the audience to have a more profound effect on the overall journalism ecosystem.

Personally and from a user experience perspective, I’d like to have the ability to subscribe to an article I read and enjoyed so that I can come back to it at a prescribed later date to see what the further thoughts on it were. As things stand, it’s painfully difficult and time consuming as a reader to attempt to engage on interesting pieces at a deeper level. Publications that can do this type of coverage and/or provide further analysis on ongoing topics will also have a potential edge over me-too publications that are simply rehashing the same exact stories on a regular basis. Outlets could also leverage this type user interface and other readers’ similar desire to increase their relationship with their readers by providing this value that others won’t or can’t.

Want more on “The IndieWeb and Journalism”?
See: Some thoughts about how journalists could improve their online presences with IndieWeb principles along with a mini-case study of a site that is employing some of these ideas.

In some sense, some of this journalistic workflow reminds me how much I miss Slate.com’s Today’s Papers feature in which someone read through the early edition copies of 4-5 major newspapers and did a quick synopsis of the day’s headlines and then analyzed the coverage of each to show how the stories differed, who got the real scoop, and at times declare a “winner” in coverage so that readers could then focus on reading that particular piece from the particular outlet.

Backfeed in action

What do you think about this idea? Will it change journalism and how readers consume it?

As always, you can feel free to comment on this story directly below, but you can also go to most of the syndicated versions of this post indicated below, and reply to or comment on them there. Your responses via Twitter, Facebook, and Google+ will be backfed via Brid.gy to this post and appear as comments below, so the entire audience will be able to see the otherwise dis-aggregated conversation compiled into one place.

If you prefer to own the content of your own comment or are worried your voice could be “moderated out of existence” (an experience I’ve felt the sting of in the past), feel free to post your response on your own website or blog, include a permalink to this article in your response, put the URL of your commentary into the box labeled “URL/Permalink of your Article”, and then click the “Ping Me” button. My site will then grab your response and add it to the comment stream with all the others.

Backfeed on!

H/T to Ryan Barrett for pointing out the BuzzFeed article.

Buzzfeed implements the IndieWeb concept of backfeed to limit filter bubbles was originally published on Chris Aldrich | Boffo Socko