First, a couple of examples/case studies.

1. About ten years ago I was trying to figure out how to get started with Node.js. I knew a little JavaScript, but nothing I read about Node made it click. It's server software, so there must be a way to write an HTTP server? From there, I read all the details about the power it has, but what I needed was a Hello World script. Brent Simmons gave me the script, and step by step instructions on how to write it.

I followed his steps, and it worked, and of course I wrote a blog post about it. That was the key I needed that unlocked what Node is, and helped me see what I could do with it. The first thing I did was factor out some of the bits so I could make it even simpler and then I built. I just wanted a few lines of code that created a server and responded to requests. All I needed was a Hello World to get me going.

Now Brent knew that I knew the basics of HTTP servers, we both worked together on a huge app that had as a small part of it a full HTTP server, thanks to Wes Felter who wrote it, no one asked him to, one day he showed up with a server that ran in Frontier. I was ecstatic. That's the key. If you have something that isn't truly new, that might have some analogies in other worlds, if you want people in those other worlds to know how to get started, give them the beginning. The first step.

1. Another example. How I learned to create and edit a website. It was 1994. I loved the web the way I love ChatGPT today. I knew how to use it, but I didn't know how to make it. Everyone told me it was really simple and they sent me links to all the docs, but they made no sense, because they talked about things I didn't understand. What I really needed was a way to make a web page that was as simple as the one Brent provided for Node-based HTTP servers, with tools and concepts I knew how to use. I found one, a service provided by Ohio State University. You emailed a message to them and they put it "on the web" and sent you back a link to the page. Click the link and there's what you typed. I tried Hello World and got back a link to a page that said Hello World. So I tried something more complicated, I did a view source of Hotwired.com's home page, and copy and pasted it into an email. That worked too (with broken images because the urls were relative).

Everything I've ever learned how to do required me to first understand it at this level.

Okay here we are in 2024, and I want to understand what Bluesky is. I know how to use it, but I don't know how to make it. But I would be surprised if it is any more complicated that writing a web content management system that uses feeds, something I've done many times. I know the components of a message, have iterated over it for the last thirty years. I even wrote the spec that defines them in RSS 2.0. We're all doing the same thing over and over and Bluesky is no different. I hear there's some nice design for the protocol, but right now I don't care. I want my Hello World. The minimal code I need to add a node to the network defined by Bluesky and I want to see what it can do with the same kind of aha moment I had with the web. I want it to work when I try it, and I want it to reveal what Bluesky is beyond what I can see from using it. I want to begin to understand the opportunities for interop.

Why do I ask? For one, I'm a student of this stuff, and I want to understand. But I also am very active in this area, and interop is my product (really read that piece, I mean it, and I think it's Bluesky's product too). I'm into working together -- it happens so infrequently. So here I'm also trying to show not just you how to explain what you do for a curious but time-limited developer, but I want to make this a this.how document that explains how to do it for everyone, hoping that we as an art and industry start explaining ourselves better to each other, because we absolutely need to do this much better imho, ymmv, mmlm, etc.

To summarize -- assume I know how the web works. I've worked with the structures and protocols for systems that are very much like Bluesky. Don't try to explain the design of the protocol, just use it to solve a problem that I will understand because I use the product and I have developed lots of stuff like it. It should be possible to show us, to teach us, what your product does.

PS: It could take a few days to put a Hello World together. Because once you do the first iteration, you may think of a more direct way to illustrate the idea, and you should do it, iterate until it works, until you can't make it any simpler.

PPS: And if you don't want to do it, that's okay too. I just thought it was worth the effort to explain what's needed to foster a greater understanding of what you're doing and what the opportunities for interop are.