I've been feeling like the Webmention page on the IndieWeb wiki doesn't do a very good job of explaining what Webmention does for users, and jumps too quickly into spec details. I would like to be able to direct people at this page when I am talking to them online about what Webmention can do, which often means what I am trying to show them is how Webmention can be used to display comments and other interactions on a website. Today I started to make some incremental improvements.
I rephrased the introduction section to start with user-facing features, rather than be a description of the protocol. Starting by updating the first sentence to describe the end result rather than a summary of the of the spec. Previously, the first sentence was:
Webmention is a simple way to notify any URL when you link to it on your site.
The problem with the original definition was it only describes one side of what Webmentions do (sending) and doesn't talk about receiving. Most importantly, it doesn't actually tell you why you would want to use it.
I changed that to:
Webmention is a protocol that enables conversations across the web.
I'm no expert at writing or branding, but I think this is an improvement because it starts off by describing the end result. Feel free to offer suggestions for alternatives though!
Interestingly, the second sentence was already great, and now flows nicely after this high-level description.
This powerful building block is used for federated comments, likes, reposts, and other rich interactions across the decentralized social web.
I then went through a bunch of the IndieWeb Examples of sites that support Webmention, found illustrative examples of their sites displaying comments, and uploaded a bunch of screenshots to the wiki. My hope is that this will help people understand the end result of supporting Webmention, which is that discussions can take place across websites.
I cleaned up the bottom section of the page a bit, consolidated the "Resources" section which had previously been split out into new pages, and I found two quotes from some of the linked articles I liked which I pulled snippets of into the page.
My ultimate goal with this is to improve the webmention.net page to be something I feel good about sending people to to get an idea of what Webmention is. Now that we are starting to expand greater into generation 2, we need to improve the documentation of the various IndieWeb components to focus less on code and protocols, and more on the end goals.
I want to start by cleaning up the Webmention page on the wiki, and I would love more help with that part of it. Feel free to continue editing the copy, improving the information hierarchy, and anything else you can think of to make it more approachable to newcomers!
Once we get to the point where the wiki page is relatively well written, I want to copy some of the content over to webmention.net, and give it a facelift. I'm always hesitant to share in-progress mockups, but hopefully doing so will spur some discussion. I'm thinking something along the lines of the mockup below, but maybe with a less stock-photo-y image, and some nicer typography.
Doing incremental improvements to the wiki page rather than jumping into a whole new design will ensure that we are focusing on getting the copy right. So please won't you help me continue to improve the wiki! 😊
Following up on yesterday's update of adding a Webmention form on IndieNews' Webmention endpoint, today I finished building out the UI for submitting to IndieNews from a browser.
Now the "Submit" link includes a form where you can paste in your post's URL, in case your website doesn't send Webmentions automatically.
If you use this form to send the Webmention, then the response will be an HTML page instead of a JSON response. If the submission is successful, then it will actually return a 302 redirect to the IndieNews permalink of the post! This is a slight deviation from the Webmention spec, but it's fine because we don't really care if the browser is a spec-compliant Webmention client.
Also thanks to Chris Aldrich for the suggestion of using a dropdown for the target URL selection on the generic Webmention form.
This is the form you see when you visit the Webmention endpoint, which is not specific to the language you're on.
"Webmention works much like @mention on Twitter, Medium, Facebook, and others, but is platform independent, which means you can use it to ping any website on the internet that supports it. Imagine if you could reply to someone on Twitter from your WordPress site? Or if you could use Facebook to reply to a post on Medium?"
This was a tricky one, spawned from when sebsel failed to discover the Webmention endpoint for one of Zegnat's posts. In that case, the Webmention endpoint was a relative URL and sebsel was sending a Webmention to a URL that was also an HTTP redirect.
The new test, webmention.rocks #23, instructs you to send a Webmention to a URL that is a redirect, and that page advertises a relative URL endpoint. You'll need to make sure that the URL you pass to your relative URL resolver is the final URL after following the redirect, rather than the one you start with.
So give it a shot! Test if your relative URL resolution code works properly!
Thanks to @Zegnat and @sebsel for finding some new new edges case in Webmention discovery that deserve new tests!
The new test, #22, advertises its Webmention endpoint with a URL that is relative to the page (e.g.
<link rel="webmention" href="22/webmention">). The existing relative URL tests were absolute paths (e.g.
<link rel="webmention" href="/test/22/webmention">).
If you already handle relative URL resolution with a library then chances are you will pass this test without any new code.
Yesterday I added a Webmention form at the bottom of my posts. If you used this form, it would show you a "check status" link after accepting the Webmention request. My Webmentions are all handled by webmention.io, and its status URLs return a JSON response. This isn't particularly friendly when someone views one of these URLs in a browser, since they just see a raw JSON blob.
Today I updated webmention.io to return all responses in HTML if they're made from a browser. It checks to see if there is text/html in the Accept header, and returns HTML if so, otherwise returns JSON as normal. Now when you view one of these status links, you'll see something like this.
Since the Webmention spec doesn't define the body of the response, doing this is still considered conformant to the spec. The one non-standard thing I had to do was to return an HTTP 303 response when accepting the Webmention instead of 201, in order to get the browser to redirect to the status URL immediately. I still return 201 to non-browser clients so they won't see any change.