DEV Community

Cover image for Improving Mastodon developer documentation
Andy Piper
Andy Piper

Posted on

Improving Mastodon developer documentation

Aloha! It has been a little while.

Some personal news...

Last month, Eugen aka @Gargron announced that I'll be working on a part-time basis with Mastodon gGmbH to support efforts around developer community and resources - aka, Developer Relations.

I've been a supporter of the free and open Web since it began; I've been all-in on the Fediverse for some time now; and I'm excited to be able to bring my experience in DevRel, particularly around community, APIs, and developer experience, to the Mastodon project. This is also cool, because I've previously been posting about the opportunity for developers in this space.

First steps

There are a number of things to work on, and it's important to be realistic about how swiftly we can get to them all. The very first thing that I wanted to do was to do a full review of the libraries and SDKs that developers have built on top of the Mastodon API, and publish an update to the relevant page in the developer documentation.

I'd like to take a moment to explain why I chose this as my first task as I believe it's relevant in the context of #DevRel - I posted about this on Mastodon yesterday, too.

Image of a Mastodon post with the text "In my long experience in #DevRel for APIs and platforms, the folks who take the time to build opinionated / language-specific libraries around an API help their own communities a lot, and also, can help to spot areas where an interface needs work, or documentation could be improved. They can be some of the key supporters in building a wider community around a platform."

A few years ago, when I was working on another platform, I took the time to do something similar. The platform itself had an HTTP-based, RESTful API that had been made available and mostly documented, but the organisation didn't publish any code or their own libraries or SDKs - the developer community jumped in and built their own. I spent a bunch of time back then scouring the internet, seeking out as many implementations of the API as possible, figuring out which ones were most used or most popular, which ones had become unmaintained, which ones were constantly evolving, which new coding languages had emerged since the platform's API was first released.

(side note: it was also super fun to go and deliberately hunt out less well-known languages and to see whether anyone had built an implementation yet... Zig, anyone? No? How about Nim!)

I've been working with API platforms for a long time. In my experience, the developers that go to the effort and spend their time building idiomatic language-specific libraries around an API, provide huge support to their own communities. Most organisations and platforms simply cannot hope to provide expertise in every language or framework themselves, so these community contributions provide an oversized benefit. The developers who build those libraries and SDKs, often become experts in themselves, and can be amplifiers that generate activity around a platform.

Just to pick out a couple of meaningful examples - in the update to the libraries and implementations page we just published, several of the new entries cover languages such as Kotlin that were not previously included, as well as adding several more Swift libraries - and in turn, those additions provide foundations for the excellent Android and iOS client apps that have emerged since the end of 2022.

In all, the page has jumped from a list of 35 libraries, to more than 50 - and that includes the fact that some have been removed either due to their authors explicitly archiving them, or the impression that they were no longer maintained (which could be added back if needed); and, from 21 to 26 languages represented. That's an impressive expansion of coverage, and I believe it demonstrates the level of interest and excitement around building on the Mastodon API.

A heartfelt Thank You to the developers who have created these resources. As a developer advocate, it's a joy to see the activity around the platform, and I aim to support you and your efforts to work with us.

The Mastodon API is open, free, and you are welcome to build with it.

What's next?

My next task is triaging and labelling issues and pull requests in the documentation repo on GitHub, with an aim to bring in as many of those existing contributions as we can. I am particularly focused on the API, and I am not currently so familiar with other topics (Mastodon server installation, administration, etc), so I'll be relying on additional help! I am aware that some of the issues and PRs have been waiting for a while, but I'll do what I can to get things improved here.

It's also worth sharing that we intend to apply a design update to the developer docs site (to match the main site and blog). That's a separate task to the content work that I'm looking at.

Another thing that I'm actively thinking about, is how we can move towards a more formal API specification. The obvious candidate is OpenAPI, and there has been some community work to provide something in this space already. A few folks also had a good conversation about it on Mastodon last week, and that made me aware of some of the complexities of providing this for the project. I'm open to taking on board other experiences in this area, so let me know if this is important to you. If nothing else, something like a Postman Collection which is up-to-date for the current API, seems to me like A Good Thing, to help the community test and implement things more quickly.

Going beyond curating lists of libraries and poking at API docs, I want to help to connect the dots between different projects around Mastodon itself, and the broader Fediverse! I started on the latter effort a couple of months ago (see: Supporting Fediverse developer communities), but for right now, I'm going to be spending time specifically on Mastodon, and helping the team with developer communications.

Let me know what else you might want to see from the Mastodon project from a developer perspective, and I'll be sure to add it to my list. Or, just share any Mastodon-related project you're working on, so I can help to shout about it!

Follow me on Mastodon

I hope to get to chat to you via GitHub, Discord, Mastodon, or another channel - keeping in mind that I've been tasked with community and API rather than individual end-user product features - the roadmap is full and exciting, though!

Finally, I continue to be interested in other opportunities and to build my skills in other areas (via my maker studio), so look out for more on this, soon.

Check out my personal site

Header image courtesy of Midjourney

Top comments (0)