Button Button
  • 000004 by useradmin on 2019/07/20 at 06:51 GMT
  • 000002 by useradmin on 2019/07/12 at 03:06 GMT

Page Content

# "Fediverse documentation is bad" is a stale take

If you're working on something, you're frustrated. You need to vent. Take care of yourself. That's good. You're supported

I'm not talking about that here. We'll get more directly helpful further down the page. When I say that complaining about the lack of docs is a stale take, I mean that those who don't have anything in the works posting takes about poor docs doesn't help

## The ActivityPub spec is vague by design

ActivityPub is an extension of ActivityStreams 2.0, so the specification spans 3 w3c documents and references more than one external specification. There was a lot of humility involved in the process in that relevant specifications were still in early development. The spec writers, especially Chris Lemmer-Webber, have blogged and microblogged about that extensively

Also previous efforts gained limited traction because the technologies weren't mature. Quite frankly nobody could predict what the fediverse would look like. The chief virtue of ActivityPub is that it gives us some tools to start building things without pretending to be more concrete than it is. The 2 strongest lessons to be learned from the prior art were that we didn't have all the information we need for a complete specification, but we did need some specific changes to the existing protocols. That's what we got

## A microblogging UI represents compromises

Even though ActivityPub describes general purpose social networking primitives and spends a great deal of verbiage on media types, actor types, envelope addressing, and other features, we don't have those things, yet. What we have is microblogging

Inline tagging and implied addressing aren't the ideal social experience any more than Ruby on Rails is the most performant networking platform. These were choices made in Mastodon development when the community was small. We wouldn't be having discussions about how things could be better without some arbitrary choices being made to establish our baseline. The important thing at this point in time is to develop an understanding of how to move forward

## LitePub is a best effort

When I started writing YAAPS, I wanted to provide better documentation for the fediverse. Instead, I learned first hand why most of litepub.social was 404 pages. ActivityPub is really expressive, so you can write about your ActivityPub experience in specific terms or you can provide general information from a detached vantage point. You can't do both and expect the result to be generally applicable

That's why YAAPS is backburner while I work on Sputnik. Building an entirely new social experience on ActivityPub is just too much work. You can create new types of media. You can apply Mastodon-flavour ActivityPub to existing types of media. You can improve ActivityPub implementation on media types where it already exists. I wanted to do all three. A lot of people want all three to happen, but none of us can do more than one at a time

LitePub legacy is our best current description of ActivityPub as it is with Mastodon as the primary influencer. Sputnik Opphuichi is me applying that to a Plone-like CMS - federation on content creation as well as publishing. As LitePub implementations move forward, I'll be able to develop yaaps to support development of social experiences that aren't possible without federation and that couldn't be implemented in the fediverse as it is

## We'll need to get our hands dirty

I promise that it's possible to build the thing you want. If it's worth building, you will probably be building tools and libraries for yourself. That's okay

You'll use the tools available, get as far as the current docs get you, build a service that federates with others of its own kind, then you'll start working on compatibility with other severs. My own plan is to work on Pleroma compatibility before Mastodon. I'll discuss the reasons for that at some point

It's an iterative process. The results have to connect to your ideas

Documentation could provide procedures for what had already been done, but it's important to understand that this isn't a good idea. More services working the same way as our current infrastructure would be actively harmful. The ActivityPub recommendation and LitePub describe outcomes, in different levels of detail, not procedures, because we need the development community around ActivityPub to be growing and experimenting

# Your server can't talk to others until it has something to say

The first hurdle is developing content worth federating. The network isn't sitting there eagerly awaiting any old bullshit lying around nor will the fediverse give much up to a service that isn't adding value. So if you have an idea to add intrinsic value to the exchange of ideas that's happening, start by building that. You absolutely will have the ability to build that last connection to the network when you're done

The feed of every fedi dev is filled with our struggles - except CJ, who's perfect, and kaniini, who deletes that stuff after a few weeks. Self care is a deeper mystery than ActivityPub, as our frequent lapses in mental hygiene demonstrate

## How you get content onto your server is up to you

When you build a service, you may be planning for interop with the network, but we can't plan for you. ActivityPub client to server protocol isn't necessary to federation and there isn't much reusable code in that space, especially in the form of completed user facing client programs

That's okay. It just means that you get to choose how data is going to be sent to your service

## Most services start with tightly coupled clients

Ultimately, it makes a certain sense to have your own UI use the same APIs as third party clients. They both do the same job. So why duplicate the code? More importantly, sharing coffeecode paths for internal and external applications reduces the surface for failure

Our interfaces rarely start out that way, however. When you do something new, you don't have an exhaustive list of the features you'll need to support and you don't always start with a clear idea of how you'll implement them. Even if you did, this is rather early in the process to limit yourself

## The Mastodon API is not the solution for third party clients

The Mastodon API is a REST API with an ActivityPub syntax for the message payload, so it's an obvious choice if your application is sufficiently similar to Mastodon. It's not without hidden costs, however

Mostly, that API was designed for Mastodon. The developers didn't intend for it to be used outside that project. Neither the official documentation nor third party sourcesources support server implementation. It's not really fair to limit their future options and demand labor beyond the scope of their stated intentions

This isn't trashing Pleroma or PixelFed. They're the reasons we know this

## ActivityPub C2S deserves consideration

ActivityPub client to server social protocol was designed to complement the server to server federation protocol. It's the easiest way to design for a future of end to end connectivity

ActivityPub C2S semantics (the meanings behind the vocabulary) could be interpreted as a Turing Complete language. This constitutes a proof that the protocol is sufficiently descriptive to encode any computable task. How, and whether, you expose that to those who use your service is up to you, but the design of ActivityPub is such that extensions and locally implemented behaviors can be accessed even if intermediate interfaces aren't aware of them. Using AP C2S provides future resistance for your API

## Other C2S APIs might suit your needs, too

If your big idea involves using a framework, your client API may be informed by the biases of your toolkit. Rails, Phoenix, and Laravel are MVC (model, view, controller) frameworks, which explains the REST APIs

If you're working in node or another language that typically gets early support for commercially sponsored protocols, you may benefit from using GraphQL instead of ActivityPub as a base for your client protocol

Providing federation without regard for specific implementation details is part of the design goal for ActivityPub. Network effect for client tools would be great, too, but the benefit isn't quite so evident, especially with the current state of the infrastructure

Neither is this list exhaustive. I have play by email game servers I maintain, so it might make sense for me to build an ActivityPub server for LMTP clients, for example

Choice is the point

# Federation is great, but why do you*you* want it?

There are a lot of ways to do ActivityPub badly. When you approach bridging or migrating another service to the fedi, it's important to consider how it will affect the communities involved. Famously, private messages were broadcast on Gnu Social servers when they were relayed by Pleroma instances. Other faux pas are possible, e.g. a federated wiki or game could generate an enormous volume of messages or a protocol bridge might expose signed messages from Secure Scuttlebutt to a broader audience than intended

The expectation for services implementing ActivityPub federation with the public address is human interaction. Floods and one way traffic won't be well received

## Mistakes were made

Current ActivityPub implementations are flawed. Mastodon is a resource hog. Pleroma implemented Objects as distinct from Activities even though Activities are a type of Object. Go-Fed, at one point, reached half a million lines of code. Your implementation can be flawed, too

It's okay to have 2 am toots with "PLEASE UPGRADE ASAP" in all caps. Developers make good faith effort and they also make mistakes

## Microblogging isn't the best thing

Also, we have a community centered on microblogging and, maybe, that's not a good thing. I chafe at the 500 character limit, even on software that allows 1337 or 5000 characters because I know there are people reading posts on UIs optimized for 500 characters

Masto forks that implement the Article type have a much better experience reading articles from WriteFreely instances than I have on Corgi, [Banana Dog's](https://banana.dog) fork. It was a reasonable choice at the time, but the community is outgrowing those patterns

## Copying other media services isn't great, either

So we have federated media that is a reimplementation of other media types, "but federated," and the federation style is very much informed by a requirement to be compatible with Mastodon. We already discussed why this happens above

As these services proliferate, though, we need to begin looking at them critically. Do we want to remain in the shadow of main stream social media, continually inviting comparisons, for any longer than necessary? As Facebook, GitHub, and others move to take the business models of users, not just advertisers, into their own revenue strategies, is it the best strategy to provide 1:1 replacements for models where our community (superficially, at least) doesn't seem to be keeping up?

## There are better things to do with federation

We probably need to be thinking about alternatives for our alternatives. Establishing services is a first step. Those services need to be extended in ways that showcase the strengths of federated content and workflows in order to be fully a part of our community and to meaningfully appeal to those still trapped in mainstream social media

This is an ongoing process. Even if your idea is too much of a stretch to work with the current implementations of ActivityPub, things will change. You need to be working on it already

# Don't worry about breaking the fediverse

When you implement federation, you're going to test it. A lot. If current projects are any indicator, you'll test almost a year. And things will still break. Mastodon's gawdoffal JSON will have something you missed that chokes your service or something will behave differently when TLS or a caching proxy is turned on

If you really want to have a fragile application, just try micromanaging the response of your service for all the possible configurations of ActivityPub apps and http servers out there. It approaches halting problem complexity

## Pleroma broke stuff and they're still here

##I Gabalready ismentioned tryinghow toPleroma breakwas stuffan andagent they'llin undesired operation between Mastodon and another beservice. hardHere's towhere getwe note that they're still here. They weren't "canceled"

You don't need to let ridfear of cancel culture keep you from building great things in the fediverse. If you do the right thing, make best effort, and work on any issues that happen instead of defending problems, eventually you come through

## It's okay to be MissKey

Then there's MissKey. This software has a great feature set and it doesn't always play well with Mastodon. That's fine

We need more MissKey in our 'verse. Please build the thing. Do your best. And let's take it from there

## Break things for the right reasons

Breaking things is part of growth, at least organic growth. I'm not condoning "Move fast; break things" as a business model where the cost of innovation is externalized to the detriment of the community, but I am trying to encourage those on the edge - myself especially - to take the step of [asking for the community to help](https://liberapay.com/YAAPS)

You're reading this on [Sputnik](https://gitlab.com/swift2plunder/sputnik), a wiki site that I'm transforming into a federated CMS