Is there a block diagram that documents how Discourse works

(Andrew Waugh) #1

On a similar note, I haven’t managed to find a block diagram of how the system is put together. A block diagram might help new mods and admins get an overview of how a discourse “appliance” works. It would eliminate some queries of the form:

The block diagram wouldn’t have to be too detailed, it could be as simple as, well… some blocks indicating what the block is called (droplet, docker, discourse, ruby, rails) with an indication of how the bits communicate with each other, what they do, and how to access them (ssh, /launcher enter app etc), read their logs, and configure/start/stop/update them, how/where their data and configuration are stored, and how to check the health status of each.

Better error pages?
(Jeff Atwood) #2

Feel free to create such a diagram if you feel it is necessary.

(Andrew Waugh) #3

It will take a while before I understand it well enough to create much more than a box with “technical krimram” in the center, and a border composed of the text “There be dragons” surrounding it, but I’ll try and keep some notes.

One of the problems in creating good technical documentation (not just in IT) is that by the time you’ve sussed it well enough to explain it, you tend to have lost track of how much of an enigma it seemed when you didn’t know much about it.

Which kind of ties in with the idea of complaint driven development. Do you remember the IBM and Dec system documentation sets of the '80s? WALLS of manuals, which were generally all detail, and no overview. When you went to decomission a system there was always a cupboard full of manuals, often still in their plastic shrinkwrap.