I would like to do a quick check on our Ubuntu Matrix documentation. We have been working to provide a set of documentation to help our community get started, understand concepts, manage rooms and operations. You can check our current documentation frontend here: https://ubuntu.com/community/communications/matrix
I believe it’s a good start. However, I would like to know what is missing, what is unclear, and what can be improved.
Get involved
If you have any thoughts or ideas, please feel free to reply to this thread. Documentation is a great way to make contributions, and the Discourse-powered documentation is super fun to use. Our documentation back-end is here: Developer - Ubuntu Community Hub
If you want to get involved with documentation in general, you can get in touch with the Technical Authors that run the Open Documentation Academy. You can do so on one of the following platforms:
Hi all, I wanted to post this roundup of details I found while browsing the documentation, but Discourse didn’t let me post the reply due to having more than 2 links.
I’ve uploaded the raw markdown to my website (~2.5 KiB)
I would appreciate if someone else with an older/more trusted account could crosspost it here.
Regards, Emma [it/its] (@emma:rory.gay/@emma:conduit.rory.gay), member of the Rory& System
Hi! As discussed in #matrix-ops:ubuntu.com, here’s my follow up post with feedback around the documentation.
General formatting:
Make room references URLs, so they can be clicked: #matrix-ops:ubuntu.com → [#matrix-ops:ubuntu.com](https://matrix.to/#/#matrix-ops:ubuntu.com) (assuming markdown is supported)
Anchors (titles) don’t appear to have a hyperlink to copy their location
Some details I’ve noticed:
Guide to deleting a room omits making the room private, this allows people to join back via room ID after being kicked, or even never having been in the room
This can be solved by adding an extra step, assuming users use Element:
Open room settings
Go to Security & Privacy
Under Access, select “Private (invite only)”
Guide to configure mjolnir mentions incorrect command !mjolnir check status, the correct command is !mjolnir status.
Explanation of admin permissions for mjolnir gives incorrect reasoning, the given reasons refer to the bot being a Synapse Administrator user, not a room administrator.
Administrator permissions in a room are required to configure certain properties, such as what servers aren’t allowed to interact with the room (m.room.server_acls) and who is administrator, moderator or muted (m.room.power_levels), according to a room’s default power levels.
General hints section on creating rooms would probably be a good fit in the guide on creating rooms.
It’s important that room administrators are aware of the defederation and encryption options before they create the room, given that configuring them is irreversible.
Also worth noting that encryption for public rooms has a large known performance impact on sending messages. For most servers, sending a message in a 500 member encrypted room can take up to 30 seconds assuming low network latency.
There may be more things I missed, though I think these are some important details to be clarified.
On top of checking the feedback above, and starting with some fixes, I did some additional work today:
Added the NOTE TO EDITORS banner to all Matrix documents. This banner is not rendered in the frontend, but makes it very clear to Discourse users that the post is actually the backend for our documentation.
NOTE TO EDITORS