When I said the documentation lacks a structure, this is what I meant... This isn't even all files in the "running mastodon" folder. How is anyone supposed to know where to start, what they need to read? I need to rework this into some kind of 1-2-3 story.

How about:

1. Installation
2. Configuration
3. Post-installation steps
4. Scaling up
5. Optional features

The old docs will still be on GitHub, so don't worry about that - I want to write new ones for the site. So how's this for structure?

Documentation site online with rough stubs for content. Didn't check how it looks on mobile yet

docs.joinmastodon.org/administ

Wrote this page! Describing possible moderation actions and spam-fighting methods...

docs.joinmastodon.org/usage/mo

Wrote this page! Installation instructions, modeled after the ones @staticsafe@mastodon.zombocloud.com wrote before:

docs.joinmastodon.org/administ

The ending bits are a bit of a lie for now, Mastodon does not include a `dist` directory with templates for the nginx config and systemd services, but I think it should, and I am planning to add that.

Okay, this took a whole day but I mapped out all entities in the Mastodon API along with in which version a particular attribute was added:

docs.joinmastodon.org/api/enti

Wrote this page:

User Guide: Decentralization

docs.joinmastodon.org/usage/de

Is there something you think is still missing from that page?

Wrote this page:

User Guide: Basics

docs.joinmastodon.org/usage/ba

Yay! All pages in the User Guide section have content now.

@Gargron
Who pays for the servers and dev for mastodon.social? Is that spelled out anywhere?

@Gargron haven't read it, but feeling a little concerned about docs on moderator actions and spam-fighting methods authored while watching John Wick… 😳

😜
;)

@gargron seems like that page should be under the "Administrator guide" heading rather than the "User guide".

@npd Mods are users. "Administrator guide" = "Sysadmin guide"

@gargron yeah, but most users aren't mods, right? And iptables won't be available to mods, I would think.

(I'm not bothered by or objecting to any way you want to do it, just noting a potential confusion as a non-expert reader.)

@Gargron May I suggest some notes on this page as to what a silenced/suspended user/site can see? Both remotely and locally - if troll@hater.town is following me, for instance, and my admin suspends hater.town, can troll@hater.town see my public toots?

This is a thing that I really feel nobody has a clear picture of unless they've invested the time to decipher the source or to set up a couple of instances to test with.

@anthracite @Gargron I second adding it, but an instance-level suspension will block anyone on that instance from getting anything in any of their timelines etc. but it doesn't prevent people from looking at publicly accessible web pages, such as public account pages which contain all public toots.

Public toots are always completely public. You can't prevent people from reading them via account pages without removing the account pages entirely.

@anthracite @Gargron Expecting a person you blocked to not be able to access any of your public toots ever is kind of like expecting someone you blocked on twitter to not be able to log out and read your public twitter page.

@Gargron I wonder if maybe ufw would be a better suggestion than directly using iptables?

@Gargron It's basically a frontend for iptables. The equivalent to those iptables rules is:
ufw enable
ufw allow ssh
ufw allow http
ufw allow https

It doesn't make a huge difference but I think ufw is easier to understand and maintain, and the guide seems to target inexperienced admins after all.

@Gargron thanks :) i still can’t figure out the profile metadata key/value pairs though. Should a patch on them be a json object?

@Gargron I have no idea what this means but I recognize that it must've taken a while, so thank you.

@Gargron Out of curiosity, what level of user is this aimed at?

@cambrian_era Whoever is curious enough to click on that in the menu I guess? I don't know.

@Gargron Gotcha. Was just wondering whether it was meant for the absolute novice general public or for people who are already reasonably tech savvy but don't understand decentralization.

@Gargron minor editing note: “Just like an e-mail address. For convenience sake, Mastodon allows you to skip the second part when addressing people on the same server as you....”

First sentence is a fragment, which is fine for this kind of doc but as the second sentence is on a completely diff topic it produces a but of confusion. Either rewording the first sentence or adding a return so the second sentence is a new paragraph should fix the problem

@gargron Looks okay to me. I don't have an account in the git, so can't do it myself: can you change "private" to "followers only" in this chart:
docs.joinmastodon.org/usage/pr

Or change the WebGUI ;)

@Gargron 100x yes! This page contains whole bunch of things that either everyone kept repeatedly asking during the last wave of sign-ons or something that took me a while to figure out.

One small suggestions -- as this document sets the tone for the users. Could you give a few examples of using cw, or even a screenshot of how using cw looks like? In my experience this is the thing new users get confused the most.

@Gargron

gist.github.com/avolkov/a47a4a

I would add this as a PR but I didn't find commits for this on source.joinmastodon.org, maybe this is a local branch?

@Gargron Which compels me to ask -- please add 'contributing' section to describe contribution guidelines and point to current repos where PR requests could be submitted.

@Gargron I love the picture of elephant friend there. It's a new one to me.

@Gargron Maybe some explanation why search on users and toots is different/not possible and the reasoning behind it? This is an argument I get every now and again why Mastodon is so difficult.

@Gargron decentralized examples
- retroshare
- ZeroNet

@Gargron The old upgrade instructions note that the re-precompiling of assets can be memory intensive and recommends stopping Masto services beforehand. I have to do this or the whole thing falls down on my VPS, for instance. Might be worth keeping that pointer?

Sign in to participate in the conversation
Mastodon

Server run by the main developers of the project 🐘 It is not focused on any particular niche interest - everyone is welcome as long as you follow our code of conduct!

<svg xmlns="http://www.w3.org/2000/svg"><symbol id="mastodon-svg-logo" viewBox="0 0 216.4144 232.00976"><path d="M107.86523 0C78.203984.2425 49.672422 3.4535937 33.044922 11.089844c0 0-32.97656262 14.752031-32.97656262 65.082031 0 11.525-.224375 25.306175.140625 39.919925 1.19750002 49.22 9.02375002 97.72843 54.53124962 109.77343 20.9825 5.55375 38.99711 6.71547 53.505856 5.91797 26.31125-1.45875 41.08203-9.38867 41.08203-9.38867l-.86914-19.08984s-18.80171 5.92758-39.91796 5.20508c-20.921254-.7175-43.006879-2.25516-46.390629-27.94141-.3125-2.25625-.46875-4.66938-.46875-7.20313 0 0 20.536953 5.0204 46.564449 6.21289 15.915.73001 30.8393-.93343 45.99805-2.74218 29.07-3.47125 54.38125-21.3818 57.5625-37.74805 5.0125-25.78125 4.59961-62.916015 4.59961-62.916015 0-50.33-32.97461-65.082031-32.97461-65.082031C166.80539 3.4535938 138.255.2425 108.59375 0h-.72852zM74.296875 39.326172c12.355 0 21.710234 4.749297 27.896485 14.248047l6.01367 10.080078 6.01563-10.080078c6.185-9.49875 15.54023-14.248047 27.89648-14.248047 10.6775 0 19.28156 3.753672 25.85156 11.076172 6.36875 7.3225 9.53907 17.218828 9.53907 29.673828v60.941408h-24.14454V81.869141c0-12.46875-5.24453-18.798829-15.73828-18.798829-11.6025 0-17.41797 7.508516-17.41797 22.353516v32.375002H96.207031V85.423828c0-14.845-5.815468-22.353515-17.417969-22.353516-10.49375 0-15.740234 6.330079-15.740234 18.798829v59.148439H38.904297V80.076172c0-12.455 3.171016-22.351328 9.541015-29.673828 6.568751-7.3225 15.172813-11.076172 25.851563-11.076172z" /></symbol></svg> <svg xmlns="http://www.w3.org/2000/svg"><symbol id="mastodon-svg-logo-full" viewBox="0 0 713.35878 175.8678"><path d="M160.55476 105.43125c-2.4125 12.40625-21.5975 25.9825-43.63375 28.61375-11.49125 1.3725-22.80375 2.63125-34.8675 2.07875-19.73-.90375-35.2975-4.71-35.2975-4.71 0 1.92125.11875 3.75.355 5.46 2.565 19.47 19.3075 20.6375 35.16625 21.18125 16.00625.5475 30.2575-3.9475 30.2575-3.9475l.65875 14.4725s-11.19625 6.01125-31.14 7.11625c-10.99875.605-24.65375-.27625-40.56-4.485C6.99851 162.08 1.06601 125.31.15851 88-.11899 76.9225.05226 66.47625.05226 57.74125c0-38.1525 24.99625-49.335 24.99625-49.335C37.65226 2.6175 59.27976.18375 81.76351 0h.5525c22.48375.18375 44.125 2.6175 56.72875 8.40625 0 0 24.99625 11.1825 24.99625 49.335 0 0 .3125 28.1475-3.48625 47.69" fill="#3088d4"/><path d="M34.65751 48.494c0-5.55375 4.5025-10.055 10.055-10.055 5.55375 0 10.055 4.50125 10.055 10.055 0 5.5525-4.50125 10.055-10.055 10.055-5.5525 0-10.055-4.5025-10.055-10.055M178.86476 60.69975v46.195h-18.30125v-44.8375c0-9.4525-3.9775-14.24875-11.9325-14.24875-8.79375 0-13.2025 5.69125-13.2025 16.94375V89.2935h-18.19375V64.75225c0-11.2525-4.40875-16.94375-13.2025-16.94375-7.955 0-11.9325 4.79625-11.9325 14.24875v44.8375H73.79851v-46.195c0-9.44125 2.40375-16.94375 7.2325-22.495 4.98-5.55 11.50125-8.395 19.595-8.395 9.36625 0 16.45875 3.59875 21.14625 10.79875l4.56 7.6425 4.55875-7.6425c4.68875-7.2 11.78-10.79875 21.1475-10.79875 8.09375 0 14.61375 2.845 19.59375 8.395 4.82875 5.55125 7.2325 13.05375 7.2325 22.495M241.91276 83.663625c3.77625-3.99 5.595-9.015 5.595-15.075 0-6.06-1.81875-11.085-5.595-14.9275-3.63625-3.99125-8.25375-5.91125-13.84875-5.91125-5.59625 0-10.2125 1.92-13.84875 5.91125-3.6375 3.8425-5.45625 8.8675-5.45625 14.9275 0 6.06 1.81875 11.085 5.45625 15.075 3.63625 3.8425 8.2525 5.76375 13.84875 5.76375 5.595 0 10.2125-1.92125 13.84875-5.76375m5.595-52.025h18.04625v73.9h-18.04625v-8.72125c-5.455 7.2425-13.01 10.79-22.80125 10.79-9.3725 0-17.34625-3.695-24.06125-11.23375-6.57375-7.5375-9.93125-16.84875-9.93125-27.785 0-10.78875 3.3575-20.10125 9.93125-27.63875 6.715-7.5375 14.68875-11.38 24.06125-11.38 9.79125 0 17.34625 3.5475 22.80125 10.78875v-8.72zM326.26951 67.258625c5.315 3.99 7.97375 9.60625 7.83375 16.7 0 7.53875-2.65875 13.45-8.11375 17.58875-5.45625 3.99125-12.03 6.06-20.00375 6.06-14.40875 0-24.20125-5.9125-29.3775-17.58875l15.66875-9.31c2.0975 6.35375 6.71375 9.60625 13.70875 9.60625 6.43375 0 9.6525-2.07 9.6525-6.35625 0-3.10375-4.1975-5.91125-12.73-8.1275-3.21875-.8875-5.87625-1.77375-7.97375-2.51375-2.9375-1.18125-5.455-2.5125-7.55375-4.1375-5.17625-3.99-7.83375-9.3125-7.83375-16.11 0-7.2425 2.5175-13.00625 7.55375-17.145 5.17625-4.28625 11.47-6.355 19.025-6.355 12.03 0 20.84375 5.1725 26.5775 15.66625l-15.38625 8.8675c-2.23875-5.02375-6.015-7.53625-11.19125-7.53625-5.45625 0-8.11375 2.06875-8.11375 6.05875 0 3.10375 4.19625 5.91125 12.73 8.12875 6.575 1.4775 11.75 3.695 15.5275 6.50375M383.626635 49.966125h-15.8075v30.7425c0 3.695 1.4 5.91125 4.0575 6.945 1.95875.74 5.875.8875 11.75.59125v17.29375c-12.16875 1.4775-20.9825.295-26.15875-3.69625-5.175-3.8425-7.69375-10.93625-7.69375-21.13375v-30.7425h-12.17v-18.3275h12.17v-14.9275l18.045-5.76375v20.69125h15.8075v18.3275zM441.124885 83.2205c3.6375-3.84375 5.455-8.72125 5.455-14.6325 0-5.91125-1.8175-10.78875-5.455-14.63125-3.6375-3.84375-8.11375-5.76375-13.57-5.76375-5.455 0-9.93125 1.92-13.56875 5.76375-3.4975 3.99-5.31625 8.8675-5.31625 14.63125 0 5.765 1.81875 10.6425 5.31625 14.6325 3.6375 3.8425 8.11375 5.76375 13.56875 5.76375 5.45625 0 9.9325-1.92125 13.57-5.76375m-39.86875 13.15375c-7.13375-7.5375-10.63125-16.70125-10.63125-27.78625 0-10.9375 3.4975-20.1 10.63125-27.6375 7.13375-7.5375 15.9475-11.38 26.29875-11.38 10.3525 0 19.165 3.8425 26.3 11.38 7.135 7.5375 10.77125 16.84875 10.77125 27.6375 0 10.9375-3.63625 20.24875-10.77125 27.78625-7.135 7.53875-15.8075 11.2325-26.3 11.2325-10.49125 0-19.165-3.69375-26.29875-11.2325M524.92126 83.663625c3.6375-3.99 5.455-9.015 5.455-15.075 0-6.06-1.8175-11.085-5.455-14.9275-3.63625-3.99125-8.25375-5.91125-13.84875-5.91125-5.59625 0-10.2125 1.92-13.98875 5.91125-3.63625 3.8425-5.45625 8.8675-5.45625 14.9275 0 6.06 1.82 11.085 5.45625 15.075 3.77625 3.8425 8.5325 5.76375 13.98875 5.76375 5.595 0 10.2125-1.92125 13.84875-5.76375m5.455-81.585h18.04625v103.46h-18.04625v-8.72125c-5.315 7.2425-12.87 10.79-22.66125 10.79-9.3725 0-17.485-3.695-24.2-11.23375-6.575-7.5375-9.9325-16.84875-9.9325-27.785 0-10.78875 3.3575-20.10125 9.9325-27.63875 6.715-7.5375 14.8275-11.38 24.2-11.38 9.79125 0 17.34625 3.5475 22.66125 10.78875v-38.28zM611.79626 83.2205c3.63625-3.84375 5.455-8.72125 5.455-14.6325 0-5.91125-1.81875-10.78875-5.455-14.63125-3.6375-3.84375-8.11375-5.76375-13.57-5.76375-5.455 0-9.9325 1.92-13.56875 5.76375-3.49875 3.99-5.31625 8.8675-5.31625 14.63125 0 5.765 1.8175 10.6425 5.31625 14.6325 3.63625 3.8425 8.11375 5.76375 13.56875 5.76375 5.45625 0 9.9325-1.92125 13.57-5.76375m-39.86875 13.15375c-7.135-7.5375-10.63125-16.70125-10.63125-27.78625 0-10.9375 3.49625-20.1 10.63125-27.6375 7.135-7.5375 15.9475-11.38 26.29875-11.38 10.3525 0 19.165 3.8425 26.3 11.38 7.135 7.5375 10.77125 16.84875 10.77125 27.6375 0 10.9375-3.63625 20.24875-10.77125 27.78625-7.135 7.53875-15.8075 11.2325-26.3 11.2325-10.49125 0-19.16375-3.69375-26.29875-11.2325M713.35876 60.163875v45.37375h-18.04625v-43.00875c0-4.8775-1.25875-8.5725-3.77625-11.38-2.37875-2.5125-5.73625-3.84375-10.0725-3.84375-10.2125 0-15.3875 6.06-15.3875 18.3275v39.905h-18.04625v-73.89875h18.04625v8.27625c4.33625-6.94625 11.19-10.345 20.84375-10.345 7.69375 0 13.98875 2.66 18.885 8.12875 5.035 5.46875 7.55375 12.85875 7.55375 22.465"/></symbol></svg>