Documentation of moderation tasks and functionalities

As a very fresh moderator of the instance, I find it a bit difficult to understand the tiny differences that can exist between different moderation tasks or actions and I mostly didn’t find any documentation or moderator guide (as an administration guide can exist).

I think it could be very useful, and I would be a volunteer to work on it, to write this kind of guide, because moderators are not supposed to be from high technical background, I mean not supposed to read the code source or read Github tickets to understand the aim of an action. But they need to be sure of what they do, and choose the right action to take by knowing the consequences of an action.

Is there any existing documentation, notes, code comments or talks I should use or know about?

I read the 1.5 “Admin Love” roadmap, and thought it would be maybe useful to add a documentation subcategory?


I don’t have anything for you but I really support this idea/effort!


Refreshing the documentation with this release may be a very good idea yeah.

Since documentation is it’s project, I believe can just adjust that on its own as the features get finalized.

Can you please respond with a line of questions regarding nuances or just anything you encountered, to give an easy base to call upon when improving these documentations. It would be highly appreciated.

Thanks all for your answers.

I’ll add a list of questions or remarks that I would find useful as @maloki suggested.

I got two examples for today:

  • when a user is reporting someone, it is not necessarily clear for the reporter to whom the report is sent: is it sent to the reported user’s instance moderator or to the reporter’s instance moderator? It can end-up with badly redacted messages not addressed to the right person, or even, disclosing information
  • when a moderator deal with reported toots in the Administration tools, there is a “Delete / Trash icon” button on the right of the toot (see screenshot) : it’s not very clear if this button is supposed to “delete the report” or “hide the too from the instance”. I just made the test and finally understood it was the second one, but I think it could be more explicit, even more because you cannot undo it from the administration panel

1 Like

I started the work on a moderator guide. It is under progress but available on Github.

1 Like

Wondering if it’d be worth reaching out to @staticsafe about this, and make sure you aren’t rewriting the same things at the same time, as they are also working on improving documentation.

Is there something already a work in progress from @staticsafe committed somewhere?

1 Like

My repo for my work is here:

The installing and upgrading Mastodon guides have already been merged to the main repo. I am not working on a moderation guide at the moment.