Matrix documentation discussion

Hello people of the Matrix,

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:

4 Likes

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

I’ve bumped your trust level on the site. So you should be able to post yourself now.

3 Likes

Alright, thank you!

Original content:

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.

Regards,
Emma [it/its] (Matrix: rory.gay, conduit.rory.gay), member of the Rory& System

4 Likes

Thank you, very useful! We’ll start fixing this asap.

1 Like

Fixed, thanks and good catch!

On top of checking the feedback above, and starting with some fixes, I did some additional work today:

  • Added the :construction: NOTE TO EDITORS :construction: 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.
  • Fixed all the needed tags on all Matrix documents
  • Moved all the documents to a newly created Documentation - Matrix category.
  • Created template for documentation
  • Created template for Matrix documentation
  • Created the About the Matrix Category page, and added some basic instructions on how to get involved