The missing fediverse documentation:

When I post a toot, what happens? What steps does my server take to send that toot to other servers? When people read that toot, what steps does their server take? Detailed all the way down to http calls and json-ld.

I don't mean what happens for Mastodon (or Pleroma), I mean for any fediverse-compatible server. I also don't mean ActivityPub or Lightpub, I mean what happens today, in reality, not what happens in some idealized ivory tower whitepaper.

The fediverse will not be democratized until this level of documentation exists.

@trwnh @gdorn

This was a quick effort, but I think I've got all the back and forth covered. It is difficult to know what's unclear when writing, however.

@tedu @gdorn yeah stuff like this is very helpful for readers, but to a certain extent it is also the responsibility of projects to detail this own stuff in their centralized docs. it would certainly help when trying to deal with compat issues, to not have to trudge through various issue trackers.

@trwnh oh, yes, I've been trying to at least casually mention various quirks in case somebody stumbles upon them. Not sure how useful that is, because all the little details aren't linked in one place, but I hope at least bringing a few more things into the light will eventually lead to discovery.

As an implementer, it can be annoying but you eventually figure things out. I think the network will work better with more user literacy, even for people who never go near the code. Tough call to say what should be considered essential knowledge, however I think it's probably shifted towards too technical.

@tedu it's been kind of interesting/frustrating for me, someone who's coming into the spec from the non-tech side (despite having a modicum of tech literacy) to see how many "gotchas" there are. tiny misimplementations and idiosyncracies in particular, but some big-picture things too, like making bad assumptions/decisions.

(mastodon in particular, with some of the limits it takes for granted, and how it ends up holding back the rest of the network, but not just mastodon of course...)

@tedu but for starters, even a simple "we use these properties for these things" would be a good step forward for trying to figure out how each implementation treats the http/json(ld) stuff. or "we accept these properties and transform them like so".

@tedu @trwnh With end-users suggesting new features and behaviors to the various projects, it benefits everybody if they understand the protocol better.

@tedu @trwnh This is the first seriously useful set of docs I've seen on the subject. I'm building something that'll federate, so while I'm doing so I'll give you feedback, if you'd like.

@gdorn yea, if there's anything missing or that you had to read twice, let me know.
Sign in to participate in the conversation is a cooperatively-run corner of the Fediverse. The instance is democratically governed by its members, who generally share an interest in the co-op model, but topics of discussion range widely.

If you are interested in joining our community, please review our Bylaws and Code of Conduct. If you agree with them, you may apply for membership on our instance via this link

Our instance is supported by sliding scale contributions of $1-10/mo made via Open Collective. You must have an active Open Collective account to apply for membership; you may set one up here