I reorganized and rewrote the docs for an open-source project with millions of users.

A brand new user guide

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.

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

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

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

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.

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

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.

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.