Re: Reconciling theory and in practice -- do the specs need updating?

There's nothing that needs to be changed about the specs, and Mastodon only
matters if you care to interoperate with Mastodon -- same as with any other
software. So I guess that leaves the "implementer's guide" option.
Currently this is something you will have to obtain from each project's
documentation or from things like federation.md.

More to the point: there is no one "fediverse", and any interoperability
requires not only shared context, but also shared abstractions, design
decisions, policies, and so on. Consider why Mastodon uses Webfinger at
all. Mastodon requires "users", "accounts", "profiles" to have a
"username", and for that username to be unique on a given domain, because
Mastodon uses this username-domain pair as not only a unique identifier in
their internal app logic, but also as part of the human experience in
finding and addressing people. Do you share these abstractions of "user",
"account", "profile", and "username"? Do you share the design decision of
addressing users by their username? Do you share the policy of requiring
this even though ActivityPub has its own `id` system based on HTTPS URIs
and the World Wide Web? You might not agree with some or all of these!

Federation is therefore a "best-effort", "open-world" system, where
everyone is free to do whatever they need to do for their own purposes, and
any "interoperability" must necessarily be semantic.