When thinking about feed formats, consider non-blog uses, too

[Nathan Galt]

(warning: rambly, but the last paragraph actually has a point I wanted to make)

I think we ought to reexamine why people bother with publishing changes to a written body of work in a syndication format.

First, let’s explicitly set aside podcasts and torrented-tv-showcasts.

Correct me if I’m wrong, but most feeds today that people subscribe to are ones that are connected to some sort of time-ordered publication — like a blog. An author writes a blog entry and then the blog software updates its most-recent-changes feed.

This sort of feed is:

- automatically generated by some preexisting software
- tied to a linearizable publishing flow

This isn’t the only kind of feed pipeline, though.

One of the things I wanted when starting my capsule was to _not_ have a blog or blog-generating software (like a static-site generator). Still, I wanted people to be able to have a computer automatically check back and see if I’d changed anything, so I figured I’d want _some_ kind of syndication format available to automated clients like CAPCOM and feed readers.

I’d written Atom. I’d also written things that generated Atom. While Prettier makes writing nice-looking Atom easier, I didn’t want to hand-write Atom myself.

Then I thought about JSON Feed. I never liked writing strict JSON (no comments, no trailing commas permitted), but I remembered that I have yj on my computers. This would let me write YAML (pleasant!) and generate JSON.

So I did just that, and now I have two lines in a Makefile for when I want to update the JSON version of the JSON Feed:

feed: feed.yaml
	cat feed.yaml | yj -i > feed.json

(the -i pretty-prints the JSON instead of leaving it all on one line. I _like_ having this sort of thing be at least somewhat human-readable, even if it bloats the payload for feed readers a bit.)

Now then. Let’s look at my changelog feed so we can all talk about it:

version:       https://jsonfeed.org/version/1.1
title:         my changelog thing
language:      en-US
home_page_url: gemini://gemini.whatever.example
feed_url:      gemini://gemini.whatever.example/feed.json

items:
-
  id: e98b2c33-0cde-4856-a0ea-8272005e3341
  url: gemini://gemini.whatever.example/
  content_text: Mention on the home page that I like ambient music.
  date_published: 2020-09-09T03:39:20Z
-
  id: 14f1a84c-df7e-43ce-b20c-5a40398188ef
  url: gemini://gemini.whatever.example/
  content_text: Added homepage.
  date_published: 2020-09-08T00:41:07Z

(I’ve set up a capsule. I haven’t quite managed to find hosting for it yet. Hence the .example TLD.)

I think we all want simplicity so we can get novice proto-nerds on board with Gemini, but I think it’s a minor hassle for a novice astronaut to manually write a correct JSON Feed feed for a changelog where any given page might show up repeatedly. Any given item’s `id` could just be a single number, but writing out a proper `date_published` in proper RFC 3339 is kind of a hassle unless you have a way to get the output of  date(1) in the proper format.

On the other hand, there are the various line-based gemtext file formats. I think that if we want to make yet another mini-format for link text, we ought to provide enough information so aggregators like CAPCOM and feed readers can tell when one page is being updated repeatedly.

yj: https://github.com/sclevine/yj

* “Capsule” is Geminispeak for “website”, yes?