Brainstorming: Getting started documentation

[gabek]

This is just a brainstorm and there's likely many details that are missing from these thoughts.

I would personally like to see a "Getting started building for the Fediverse" to be very small sections that are split up in logical steps. There are so many things you have to understand to have a fully functional implementation, but if we can split all this up into functional pieces where a developer can see each piece work in isolation I think it would be far more approachable.

For example, maybe we could start with building a "profile" that's viewable by looking it up on other Fediverse platforms. This is something that's relatively easy to test since you can paste in an account on other platforms and see it. Maybe we could even have a little online tester where you paste in your endpoint and it does a simple render of the primary properties as a sanity check. The properties required have a relatively small surface area to understand in comparison to other scenarios and could be a good place to start. It also introduces the idea of the Actor without having to understand a far more complex ActivityPub payload. It's gratifying to see one piece of the puzzle fully working and viewing this profile would enable that.

Then after this section is built we can move the developer to a next step, building on top of what they just built. Because they have a working Actor that is publicly available maybe then we can have them build their first Activity. And then how to sign the request. And then how to send it to inboxes.

And after they get through the "sending activities" steps we can move on to building our own inbox, parsing inbound activities, validating them, etc.

I think this style of documentation would be great. Split it up. Test each section. Build upon what you just learned. Eventually have a final product.

[jernst]

What about organizing this by accomplishment?

• Make some code that looks up a remote user
• Make some code that can be looked up by, say, Mastodon, as a remote user from their perspective
• Make some code that lets Mastodon "follow" my user
• Make some code that makes Mastodon believe my user is following them
• Make some code that gets a minimal post into the notifications of the remote user
• ....

[gabek]

Yeah exactly! Start small, introduce concepts and terminology and build upon each step. This is how I wish I was introduced to the concepts and pieces required for building on the Fediverse.

I know you specifically said "Mastodon" because it's what people are used to seeing, but I wouldn't want to write any documentation that feels Mastodon-specific. I'd probably split the difference and say the "Getting Started Guide" will walk you through being "microblog compatible" instead of Mastodon, and we can make sure it works with Pleroma, Misskey, etc.

[Clay-Ferguson]

This would be a huge help to everyone getting started in ActivityPub. Also, like you said, @gabek, breaking it up into small chunks of working code with examples will be super important so people can get instant success at each stage, rather than being overwhelmed by the W3C docs. The W3C docs are good as a reference but not that helpful to someone trying to start from scratch.

[jernst]

I still would start with Mastodon. The overwhelming likelihood right now is that a new developer wants to connect to Mastodon first, and everything else later. If the examples can be written to be generic that's fine, but we want to avoid to many if-then-else's in the little pieces.

For example, we probably want to recommend which specific instance to connect to to try out things -- we don't want people to get hung up on running afoul on somebody's TOS that precludes, say, test posts. (I for one spent too much time attempting to run my code against a local/LAN instance of Mastodon until I realized that it cannot be done without an official TLS cert -- not something I had expected.)

[pzingg]

What if we started with the AP spec, and then gradually introduce Mastodon concepts. Introducing an actor might be something like this, with code examples for each item. These are the kinds of things I had to learn a few months ago when starting out. (I apologize if some of the terminology is wrong, or the ordering is not the best).

• What's the JSON-LD format?
• What is that "@context"? What's an IRI?
• How do you refer to an actor?
• An actor has an inbox and an outbox. These are URLs that expose collections.
• An actor has other collections (the ones specifically mentioned in the AP spec) such as followers, following.
• Activities require actors (they can also have objects and targets)
• An actor can be an author ("attributedTo"), a recipient ("to", "cc", etc.), an object (for a Follow activity)
• You POST activities to the inbox URLs of recipient actors
• You GET activities from an author's outbox

Then we have the real world, where things quickly get messy, and already we will probably have to go out of the AP spec and into Mastodon conventions (explaining variants from other applications):

• How do you translate a Fediverse account @Actor@domain into an actor (webfinger)?
• What properties do actors have (profile fields, settings--discoverable, accept followers, public and private keys)?
• How do you find out the URLs for an actor's inbox and outbox, and other collections?
• What other collections do actors have in common applications (favorites, bookmarks, pinned tweets, blocked accounts)?
• What are in the different timeline collections (and what filters--with replies--can be applied to them)?
• How do you enumerate the items of these paginated collections?
• How do you authenticate an actor?
• How do you authenticate an activity to a remote server (httpsigs, public and private keys)?

At this point, a novice might have enough information that you could explain sending a Follow activity. You could show how it works at the AP level (posting directly to an inbox URL) and also via a "high level" API--Mastodon.