About the client

Mastodon is a free and libre open-source software project that aims to let anyone easily host their own Twitter-like social media website. Started in 2016, the project has since grown due to various migrations, usually spurred by the failures and mistakes of the dominant, centralized social platforms.

I have been using Mastodon since November 2016 -- you can view my profile at mastodon.social/@trwnh if you would like -- and I have grown to quite enjoy my experience there over the years. It reminds me a lot of the early days of Twitter... before they gave up on being a social network, anyway.

One of the things I love most about the culture on there is that it's very much focused on people rather than content or engagement. This significantly lowers social friction and makes everyone more or less approachable. So approachable, in fact, that I could casually reply to the creator and founder of Mastodon and get this gig out of nowhere:

Eugen

@Gargron@mastodon.social

I really want the Mastodon documentation to have a good structure rather than just all information thrown together in a pile. I'm not sure how though.

August 18, 2019, 7:42 PM

infinite love ⴳ

@trwnh@mastodon.social

@Gargron i'd be willing to take a stab at it, having just cleaned up a lot of docs for pixelfed. it's still incomplete but it's much less messy than it used to be. i would need to sit down and try to map it out with you first, though.

August 18, 2019, 8:04 PM

Eugen

@Gargron@mastodon.social

@trwnh Okay, let's do it. Paid, of course.

August 18, 2019, 8:21 PM

So... yeah, that's how this all happened.

Let me show you what I did.

A brand new user guide

User guide

Basics
Decentralization
Privacy
Moderation

Many of the pages in the old user guide did not actually deal with teaching people how to use Mastodon, so the content within them was reworked into a more general landing page that explained the benefits of Mastodon. This new landing page explains the basics of microblogging and federation, before moving into the practical implications that these decisions have for user freedom, privacy, and safety. Select quotations were included from previously published promotional material on the Mastodon blog.

What is Mastodon?

What is a microblog?
What is federation?
What is ActivityPub?
Practical implications

Choice of server provider and policy
Funding and monetization
Interoperability between different software
Free/libre software

Choose your path

After this, an entirely new user guide was outlined from scratch, covering the user life cycle from start to end (or new beginning).

Using Mastodon

Signing up for a new account
Setting up your profile
Posting toots
Using the network features
Dealing with unwanted content
Promoting yourself and others
Set your preferences
More settings
Using Mastodon externally
Moving or leaving accounts

With the information architecture phase done, writing the user guide was a straightforward task. Explanations of each feature and setting were added to the appropriate pages, as well as screenshots demonstrating proper usage. Tip boxes are included throughout in order to highlight important points.

A more expressive admin guide

Admin guide

Installation
Configuration
Post-installation steps
Scaling up
Optional features
Upgrading to a new release
Migrating servers
Troubleshooting

Running Mastodon

Preparing your machine
Installing from source
Configuring your environment
Installing optional features
Setting up your new instance
Using the admin CLI
Upgrading to a new release
Backing up your server
Migrating to a new machine
Scaling up your server
Moderation actions
Troubleshooting errors

This section was mostly straightened out already, but could still use some improvements. A pre-installation page was split out from the old installation page. Backup instructions were moved out of "Optional features" and into a dedicated page. Pages were added for moderation and CLI usage.

Giving developers more complete documentation

Development guide

Overview
ActivityPub compliance

The old "overview" page contained a mixture of information about setting up a dev environment, libraries used, code structure, and useful commands to run for testing.

The first step in cleaning this up was to split this page into multiple discrete pages, each with its own purpose. As "development" is a vague term, two new sections were created to replace it: one for client development (merged with API), and one for server development. The old "overview" pages were nested under the server development section, as they dealt primarily with server development.

Next, "ActivityPub compliance" was moved into a dedicated section for spec compliance, and pages were created for documenting how various significant specifications were used and implemented within Mastodon.

Contributing to Mastodon

Technical overview
Setting up a dev environment
Code structure
Routes

Spec compliance

ActivityPub
WebFinger
Security
Microformats
OAuth

While the basics of ActivityPub federation were already written, the format of the old document simply pointed toward the server-to-server spec, as well as HTTP Signatures and Linked Data Signatures (with no real explanation beyond that). Therefore, I rewrote this page into multiple separate pages, each detailing the spec in question. The "ActivityPub" page now covers status federation and profile federation, the properties and types used in each, HTML payload sanitization, namespacing, and extensions (with sample payloads). "WebFinger" explains what, why, and how to use WebFinger for actor URI resolution. "Security" explains HTTP and LD signatures. "Microformats" explains the use of Microformats 2.0 and how they may be parsed, and "OAuth" covers the endpoints and flows implemented within Mastodon for obtaining a token.

Helping client apps use the API

API Overview

Guidelines
Libraries
Authentication
Permissions
Entities
Parameters
Streaming API
Web Push API

REST API

Accounts
Apps
...
Timelines

This was the majority of the work. Mastodon's REST API documentation was really messy, and it showed. Finding something generally entailed flipping back and forth between multiple pages and searching within them, and each page was very long.

The first step was to promote methods and entities into their own sections. The "Entities" page was split into multiple pages, one per entity, and alphabetized. Tables were converted into headings, to allow for providing more information about each field.

Methods were grouped by namespace rather than by feature-set, and with one level of nesting depending on whether the methods within pertained to accounts, statuses, timelines, notifications, etc. The pages for the Streaming and Web Push APIs were moved out of the overview section and into the methods section.

Finally, a new section was created for a client development guide. The guide would cover the basics of REST API, how to make requests, how responses are structured, and authentication/authorization.

Developing Mastodon Apps

Getting started with the API
Playing with public data
Obtaining client app access
Logging in with an account
Guidelines and best practices
Libraries and implementations

REST API

Guidelines and best practices
OAuth Scopes

API Methods

apps

oauth

accounts

bookmarks
favourites
mutes
...

statuses

media
polls
scheduled_statuses

timelines

conversations
lists
markers
streaming

notifications

push

search
instance

trends
directory
custom_emoji

admin
proofs
oembed

API Entities

Account
Activity
Admin::Account
Admin::Report
...
Status
Tag
Token

Writing this section taught me a lot about the basics of REST APIs, understanding HTTP requests and responses, providing parameters, and how OAuth works -- all information that I included in the client development guide.

While documenting the REST API, I had to consult the Ruby on Rails routing config file extensively, so I took it as an opportunity to write a page about how routes work and how to read the routes file.

The results were very much appreciated.

bless you for being here to work on the docs btw it's a big relief

{{< people/gargron>}} Eugen "Gargron" Rochko
Mastodon founder
& lead developer

There was much less missing information.

During the information architecture phase, a new skeleton was created as a proposed alternative structure. This process made the existing gaps in the old structure more obvious, and therefore those gaps could be filled during the technical writing phase.

It was also easier to make additions in an appropriate place.

For example, the following pages were added after completion:

"Rate limits" was added under "REST API", describing how to deal with rate limits on requests made to the REST API.
"Bug bounties and responsible disclosure" was added under "Contributing to Mastodon", describing where serious issues should be reported if found.
"Running your own server" was added under "Using Mastodon", describing the reasons why a user might want to run their own server and linking to the "Running Mastodon" section.

The clear structure left in place by my information architecture work meant that it was almost immediately clear where to add these pages.

The quality and formatting of the docs was vastly improved.

Methods now include the HTTP verb, endpoint, description, return type, OAuth scope, version history, request parameters, and sample response code and payload.

Entities now include example payloads, as well as each attribute and its description, type, and version history.

Maybe you'd appreciate me doing something similar for you?

Check out the live version Email me a proposal