Button Button
  • 000002 by useradmin on 2019/07/12 at 03:06 GMT
  • 000001 by useradmin on 2019/07/11 at 20:21 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 conclusiveconcrete 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 arbitrarilyarbitrary 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'tcan write about your ActivityPub projectexperience in specific terms or you can provide general information from a detached vantage point. You can't do both and expect thatthe experienceresult 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 wantwanted 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.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 CMSPlone-like that is more collaborative thanCMS current- federatedfederation blogson -content likecreation Ploneas insteadwell ofas WordPress.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 coffee 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 source 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 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

# Federation is great, but why do 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

## Microblogging isn't the best thing

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

## There are better things to do with federation

# Don't worry about breaking the fediverse

## Pleroma broke stuff and they're still here

## Gab is trying to break stuff and they'll be hard to get rid of

## It's okay to be MissKey

## Break things for the right reasons