393 lines
16 KiB
HTML
393 lines
16 KiB
HTML
---
|
|
title: "Mastodon documentation revamp"
|
|
summary: "Reorganizing the documentation for the Mastodon Project, while also rewriting significant portions of it."
|
|
author: "Abdullah Tarawneh"
|
|
date: "2020-01-04"
|
|
start: "Aug 2019"
|
|
end: "Jan 2020"
|
|
at: "Mastodon"
|
|
position: "Information Architect / Documentation Specialist"
|
|
tags: ["mastodon", "documentation", "information architecture", "rest api"]
|
|
category: "Work"
|
|
cover: "/images/mastodocs.jpg"
|
|
---
|
|
|
|
<main id="mastodon">
|
|
<header class="page-header section">
|
|
<div class="container">
|
|
<img src="/icons/mastodon.png" alt="">
|
|
<h1 class="page-title">I reorganized and rewrote the docs for an open-source project with millions of users.
|
|
</h1>
|
|
</div>
|
|
</header>
|
|
<section class="section" id="about">
|
|
<div class="container">
|
|
<h2 class="title">About the client</h2>
|
|
<p><a href="https://joinmastodon.org" target="_blank">Mastodon</a> 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.</p>
|
|
<p>I have been using Mastodon since November 2016 -- you can <a href="https://mastodon.social/@trwnh"
|
|
target="_blank">view my profile at mastodon.social/@trwnh</a> 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
|
|
<a href="/blog/twitter-not-social" target="_blank">they gave up on being a social network</a>, anyway.</p>
|
|
<p>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:</p>
|
|
|
|
<div class="conversation">
|
|
|
|
<iframe src="https://mastodon.social/@Gargron/102640868158739158/embed" class="mastodon-embed"
|
|
style="max-width: 100%; border: 0" width="400" allowfullscreen="allowfullscreen"></iframe>
|
|
<script src="https://mastodon.social/embed.js" async="async"></script>
|
|
|
|
<iframe src="https://mastodon.social/@trwnh/102640952580526770/embed" class="mastodon-embed"
|
|
style="max-width: 100%; border: 0" width="400" allowfullscreen="allowfullscreen"></iframe>
|
|
<script src="https://mastodon.social/embed.js" async="async"></script>
|
|
|
|
<iframe src="https://mastodon.social/@Gargron/102641022258942590/embed" class="mastodon-embed"
|
|
style="max-width: 100%; border: 0" width="400" allowfullscreen="allowfullscreen"></iframe>
|
|
<script src="https://mastodon.social/embed.js" async="async"></script>
|
|
|
|
</div>
|
|
|
|
<p>So... yeah, that's how this all happened.</p>
|
|
</div>
|
|
</section>
|
|
<section class="section" id="overview">
|
|
<div class="container">
|
|
<h2 class="title">So, what did all this entail?</h2>
|
|
<section id="ia">
|
|
<h3 class="subtitle">Information Architecture</h3>
|
|
<p></p>
|
|
</section>
|
|
<section id="writing">
|
|
<h3 class="subtitle">Documentation Writing</h3>
|
|
<p></p>
|
|
</section>
|
|
</div>
|
|
</section>
|
|
<section class="section" id="process">
|
|
<div class="container">
|
|
<h2 class="title">Let me show you how I applied my process.</h2>
|
|
<section id="user">
|
|
<h3 class="subtitle">A brand new user guide</h3>
|
|
<div class="structure">
|
|
<div class="old card">
|
|
<h4 class="card__head">User guide</h4>
|
|
<ul class="card__body">
|
|
<li>Basics</li>
|
|
<li>Decentralization</li>
|
|
<li>Privacy</li>
|
|
<li>Moderation</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<p>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.</p>
|
|
|
|
<div class="structure">
|
|
<div class="new card">
|
|
<h4 class="card__head">What is Mastodon?</h4>
|
|
<ul class="card__body">
|
|
<li>What is a microblog?</li>
|
|
<li>What is federation?</li>
|
|
<li>What is ActivityPub?</li>
|
|
<li>Practical implications</li>
|
|
<ul>
|
|
<li>Choice of server provider and policy</li>
|
|
<li>Funding and monetization</li>
|
|
<li>Interoperability between different software</li>
|
|
<li>Free/libre software</li>
|
|
</ul>
|
|
<li>Choose your path</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<p>After this, an entirely new user guide was outlined from scratch, covering the user life cycle from start
|
|
to end (or new beginning).</p>
|
|
|
|
<div class="structure">
|
|
<div class="new card">
|
|
<h4 class="card__head">Using Mastodon</h4>
|
|
<ul class="card__body">
|
|
<li>Signing up for a new account</li>
|
|
<li>Setting up your profile</li>
|
|
<li>Posting toots</li>
|
|
<li>Using the network features</li>
|
|
<li>Dealing with unwanted content</li>
|
|
<li>Promoting yourself and others</li>
|
|
<li>Set your preferences</li>
|
|
<li>More settings</li>
|
|
<li>Using Mastodon externally</li>
|
|
<li>Moving or leaving accounts</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
</section>
|
|
<section id="admin">
|
|
<h3 class="subtitle">A more expressive admin guide</h3>
|
|
<div class="structure">
|
|
<div class="old card">
|
|
<h4 class="card__head">Admin guide</h4>
|
|
<ul class="card__body">
|
|
<li>Installation</li>
|
|
<li>Configuration</li>
|
|
<li>Post-installation steps</li>
|
|
<li>Scaling up</li>
|
|
<li>Optional features</li>
|
|
<li>Upgrading to a new release</li>
|
|
<li>Migrating servers</li>
|
|
<li>Troubleshooting</li>
|
|
</ul>
|
|
</div>
|
|
<div class="new card">
|
|
<h4 class="card__head">Running Mastodon</h4>
|
|
<ul class="card__body">
|
|
<li>Preparing your machine</li>
|
|
<li>Installing from source</li>
|
|
<li>Configuring your environment</li>
|
|
<li>Installing optional features</li>
|
|
<li>Setting up your new instance</li>
|
|
<li>Using the admin CLI</li>
|
|
<li>Upgrading to a new release</li>
|
|
<li>Backing up your server</li>
|
|
<li>Migrating to a new machine</li>
|
|
<li>Scaling up your server</li>
|
|
<li>Moderation actions</li>
|
|
<li>Troubleshooting errors</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<p>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.</p>
|
|
</section>
|
|
<section id="dev">
|
|
<h3 class="subtitle">Giving developers more complete documentation</h3>
|
|
<div class="structure">
|
|
<div class="old card">
|
|
<h4 class="card__head">Development guide</h4>
|
|
<ul class="card__body">
|
|
<li>Overview</li>
|
|
<li>ActivityPub compliance</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
<p>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.
|
|
</p>
|
|
<div class="structure">
|
|
<div class="new card">
|
|
<h4 class="card__head">Contributing to Mastodon</h4>
|
|
<ul class="card__body">
|
|
<li>Technical overview</li>
|
|
<li>Setting up a dev environment</li>
|
|
<li>Code structure</li>
|
|
<li>Routes</li>
|
|
</ul>
|
|
</div>
|
|
<div class="new card">
|
|
<h4 class="card__head">Spec compliance</h4>
|
|
<ul class="card__body">
|
|
<li>ActivityPub</li>
|
|
<li>WebFinger</li>
|
|
<li>Security</li>
|
|
<li>Microformats</li>
|
|
<li>OAuth</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<p>
|
|
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.
|
|
</p>
|
|
</section>
|
|
<section id="api">
|
|
<h3 class="subtitle">Helping client apps use the API</h3>
|
|
<div class="structure">
|
|
<div class="old card">
|
|
<h4 class="card__head">API Overview</h4>
|
|
<ul class="card__body">
|
|
<li>Guidelines</li>
|
|
<li>Libraries</li>
|
|
<li>Authentication</li>
|
|
<li>Permissions</li>
|
|
<li>Entities</li>
|
|
<li>Parameters</li>
|
|
<li>Streaming API</li>
|
|
<li>Web Push API</li>
|
|
</ul>
|
|
</div>
|
|
<div class="old card">
|
|
<h4 class="card__head">REST API</h4>
|
|
<ul class="card__body">
|
|
<li>Accounts</li>
|
|
<li>Apps</li>
|
|
<li>...</li>
|
|
<li>Timelines</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
<div class="structure new">
|
|
<div class="new card">
|
|
<h4 class="card__head">Developing Mastodon Apps</h4>
|
|
<ul class="card__body">
|
|
<li>Getting started with the API</li>
|
|
<li>Playing with public data</li>
|
|
<li>Obtaining client app access</li>
|
|
<li>Logging in with an account</li>
|
|
<li>Guidelines and best practices</li>
|
|
<li>Libraries and implementations</li>
|
|
</ul>
|
|
</div>
|
|
<div class="new card">
|
|
<h4 class="card__head">REST API</h4>
|
|
<ul class="card__body">
|
|
<li>OAuth Scopes</li>
|
|
</ul>
|
|
</div>
|
|
<div class="new card methods">
|
|
<h4 class="card__head">API Methods</h4>
|
|
<ul class="card__body">
|
|
<li>apps</li>
|
|
<ul>
|
|
<li>oauth</li>
|
|
</ul>
|
|
<li>accounts</li>
|
|
<ul>
|
|
<li>bookmarks</li>
|
|
<li>favourites</li>
|
|
<li>...</li>
|
|
</ul>
|
|
<li>statuses</li>
|
|
<ul>
|
|
<li>media</li>
|
|
<li>...</li>
|
|
</ul>
|
|
<li>timelines</li>
|
|
<ul>
|
|
<li>conversations</li>
|
|
<li>...</li>
|
|
<li>streaming</li>
|
|
</ul>
|
|
<li>notifications</li>
|
|
<ul>
|
|
<li>push</li>
|
|
</ul>
|
|
<li>search</li>
|
|
<li>instance</li>
|
|
<ul>
|
|
<li>trends</li>
|
|
<li>directory</li>
|
|
<li>custom_emoji</li>
|
|
</ul>
|
|
<li>admin</li>
|
|
<li>proofs</li>
|
|
<li>oembed</li>
|
|
</ul>
|
|
</div>
|
|
<div class="new card entities">
|
|
<h4 class="card__head">API Entities</h4>
|
|
<ul class="card__body">
|
|
<li>Account</li>
|
|
<li>Activity</li>
|
|
<li>Admin::Account</li>
|
|
<li>Admin::Report</li>
|
|
<li>...</li>
|
|
<li>Status</li>
|
|
<li>Tag</li>
|
|
<li>Token</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
</section>
|
|
</div>
|
|
</section>
|
|
<section class="section" id="outcomes">
|
|
<div class="container">
|
|
<h2 class="title">The results were very much appreciated.</h2>
|
|
<blockquote class="praise">
|
|
bless you for being here to work on the docs btw it's a big relief
|
|
</blockquote>
|
|
<div class="attribution">
|
|
<img src="/images/gargron.jpg" alt="Gargron's avatar">
|
|
<cite><em>Eugen "Gargron" Rochko</em><br>Mastodon founder<br>& lead developer</cite>
|
|
</div>
|
|
<h3 class="subtitle">There was much less missing information.</h3>
|
|
<p>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.</p>
|
|
<h3 class="subtitle">It was also easier to make additions in an appropriate place.</h3>
|
|
<p>For example, the following pages were added after completion:</p>
|
|
<ul>
|
|
<li>"Rate limits" was added under "REST API", describing how to deal with rate limits on requests made to
|
|
the REST API.</li>
|
|
<li>"Bug bounties and responsible disclosure" was added under "Contributing to Mastodon", describing where
|
|
serious issues should be reported if found.</li>
|
|
<li>"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.</li>
|
|
</ul>
|
|
<p>The clear structure left in place by my information architecture work meant that it was almost immediately
|
|
clear where to add these pages.</p>
|
|
<h3 class="subtitle">The quality and formatting of the docs was vastly improved.</h3>
|
|
<p>Methods now include the HTTP verb, endpoint, description, return type, OAuth scope, version history, request
|
|
parameters, and sample response code and payload.</p>
|
|
<p>Entities now include example payloads, as well as eacha ttribute and its description, type, and version
|
|
history.</p>
|
|
</div>
|
|
</section>
|
|
<hr class="separator">
|
|
<section class="section" id="cta">
|
|
<div class="container">
|
|
<h2 class="title">Maybe you'd appreciate me doing something similar for you?</h2>
|
|
<img src="/images/mastodocs.png" alt="Mastodon documentation landing page">
|
|
<div class="buttons">
|
|
<a href="https://docs.joinmastodon.org" class="demo button"><i class="fa fa-globe"></i>Check out the live
|
|
version</a>
|
|
<a href="mailto:a@trwnh.com" class="email button"><i class="fa fa-envelope"></i>Email me a proposal</a>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
</main> |