document the system in a GitHub wiki or the source code

[anarcat]

this specific repository documents somewhat correctly the deployment of a single node, but is lacking a lot of things.

a few examples:

• it assumes someone is already familiar with Docker swarm, which might not be the case for all operators. it's a high bar to set and should have a similarly high requirement for documentation, including something that could be available offline
• it lacks documentation on how to setup Deltachat service
• it has very limited diagnostics/debugging instructions: what are the common failure modes? what happens when internet goes down?
• it doesn't document many of the matrix pitfalls: how do i create a room? how do i make it visible on all servers? how do servers talk to each other (or not)? how do i handle moderation?
• it doesn't explain why the current technological choices were made nor which alternatives were considered... those might seem obvious to you right now, but they are not for an outsider, and will likely be unclear to you in the long term as well
• it lacks contact information for support: who do we call for help when this breaks?

I understand it might seem like a lot, including a lot of stuff that's out of scope. But the idea here is that this system should be self-sufficient, especially when running offline. Whenever you link to an external document like (say) docker-swam you need to think about what happens when the internet is not available and that link doesn't work anymore.

That's kind of a worst case scenario, but a more likely (but similar in impact) scenario is where a user has never used docker (let alone docker-swarm) and needs to start from scratch. Do they install linux? which distro? how?

This is where things like using Linux distributions for packaging (e.g. #11 ) really shine because those typically ship with a user manual as well. This is something the freedombox project does particularly well as well.

Think of this as the "owner manual" you get when you buy a car, except it should also show you how to change the tires, do an oil change, or fix the spark plugs (something which car manuals do less and less).