User guide for accessing the Matrix server

of Assemblée Virtuelle

Needs to be reviewed and validated.

1 files changed, 116 insertions, 0 deletions

diff --git a/USAGE_GUIDE.en.md b/USAGE_GUIDE.en.md
new file mode 100644
index 0000000..10fd3ca
--- /dev/null
+++ b/USAGE_GUIDE.en.md
@@ -0,0 +1,116 @@
+# User guide
+
+> v0.2 (Nov 16, 2018)
+
+## Introduction
+
+**Matrix** is now used for Virtual Assembly discussions, replacing Slack. A Matrix server is self-hosted on the association server, and responds to the domain name **matrix.virtual-assembly.org**.
+
+The principle of Matrix is a juxtaposition of "rooms", spread over a *federation of servers*, which are all independent of each other (and not hierarchical). These rooms can be grouped into **communities**<sup>1</sup> (*groups*) which are divided into filters across all Matrix federation. A room can belong to several communities. Each community has at least one room with the same name.
+
+For example, there is a **General** community, which currently includes two rooms: *General* and *Reception*.
+
+## Accessing rooms — Tools
+
+To access the conversations of the Matrix federation (and more specifically in our case of the Virtual Assembly) you can either:
+
+1. Use the web interface at the following address:
+[Virtual Assembly Community]. You will then land on a page presenting the rooms of the **General** community.
+1. Use a client software, of which there is a list accessible on this page: [Matrix clients]. For our part, we recommend [Riot] which is available as both desktop and mobile applications. It is currently the most mature application to access Matrix. As you will see, the web interface itself uses Riot.
+
+In order to access community discussions, you need to have a **Matrix** account, no matter which server you are registered on. However, your user experience could be different depending on your account (see Configuration)
+
+## Creating an account
+
+*The following section is only about Riot. Other clients are not documented here yet.*
+
+When you want to join a community or access a room, you will be asked to create an account, unless you are not already registered somewhere on the Matrix network.
+
+The instance of the Virtual Assembly is not public. You have to be granted by the sysadmin team of the Assembly, so check tha point first: If you were on Slack, or have been in contact with the Assembly for a long time, it is likely that this is the case. Otherwise, contact someone you know in the Assembly, so that this person alerts the sysadmin team to allow access to the Virtual Assembly rooms<sup>3</sup>. You will soon be notified to create an account.
+
+Depending on which page you are on, you can see two different messages. The difference between "**Join the community**" and "**Join the room**" is that, in the first case, you will see the community icon in the far left sidebar of the window. You can be part of as many communities as you want and these ones will visually separate the rooms following different domains of interest.
+
+For the rest, the registration process is the same in both cases.
+
+> **Beware**: on the web interface, you will see a pop-up window; then click on "*select another server*"
+
+To create an account, fill out the form as follows:
+1. Enter your e-mail address <sup>2</sup>, but ...
+1. **... do not fill in the Phone field** (this causes a bug).
+1. Choose a username and a password
+1. Before clicking on **Register**:
+  1. You must choose the server that will host your account ->
+    * the **Default Server** is on the domain https://matrix.org
+    * the **Custom Server** is the one of the Virtual Assembly (we strongly advise you to choose this option).
+  1. For the home service URL, enter: https://matrix.virtual-assembly.org
+  1. For the identity server URL, leave the default value: https://riot.im
+  1. Choose the language for the interface
+1. You can now click on **Register**
+
+Fill out the form giving your email address indicates your membership (or not) in the Virtual Assembly (the addresses were taken from Slack).
+
+Once connected, you can join the different rooms, whose icons will be added in the second left sidebar; you can then sort them by priority.
+
+Communities and rooms IDs are standardized as follows:
+
+|-------------|--------------------------------------|
+| room        | # {salon name}: {chat server}        |
+| ------------|--------------------------------------|
+| community   | + {community name}: {chat server}    |
+|-------------|--------------------------------------|
+
+Thus, the **Ontologies** room has for identifier:
+> #ontologies:matrix.virtual-assembly.org
+
+To access it from the web, we must add the radical
+** https: //riot.im/app/#** followed by ** / group ** or ** / room ** as appropriate.
+> e.g. : https://riot.im/app/#/room/#ontologies:matrix.virtual-assembly.org
+
+## User interface
+
+### Toolbar
+
+At the bottom left of the window, you will see a toolbar with the following features :
+
+![Toolbar](Riot_Tools1.png "Outils")
+
+- Add a community (to existing list)
+- Riot Home page
+- Start a discussion with someone<sup>4</sup>
+- Display the catalog of rooms (list depending of your home server)
+- Create a new room
+- Parameters of your personal profile
+
+> **Attention** : Le répertoire des salons que vous voyez dépend du serveur Matrix sur lequel vous avez votre compte. Si c'est sur l'instance de l'Assemblée Virtuelle, tout ira bien, sinon vous verrez la liste des salons de matrix.org, ce qui ne vous sera pas d'une grande utilité, d'autant que vous ne pourrez pas faire de recherche.
+
+## Usage
+
+### Mentions
+- To mention a person in a conversation, insert the annotation "@pseudo_of_the_person" (as in Slack)
+- You can mention at once all the subscribers of a room with the annotation "@room".
+- You can mention another room in a discussion by prefixing its name with a hash "#".
+- For doing the same with a community, prefix its name with the symbol “+”.
+
+## Best practices
+
+1. Ne laissez pas votre avatar vide, et mettez une image facilement discernable.
+
+## Notes
+1. “commmunity” is the term used by Riot, as an equivalent for Matrix “group”
+1. The workflow is no yet formally approved
+1. If you already joined chats on Slack, be careful to keep the same e-mail address you uded there.
+1. ”Direct messages” on Slack.
+
+
+
+[Virtual Assembly Community]: <https://riot.im/app/#/group/+general:matrix.virtual-assembly.org>
+"Page d'accueil de la communauté Assemblée Virtuelle"
+
+[Matrix clients]: <https://matrix.org/docs/guides/faq.html#usage>
+"Introduction to common Matrix clients"
+
+[Riot]: <https://riot.im/>
+"Riot - recommended Matrix client"
+
+[Reception]: <https://matrix.to/#/!JQkKPpdjWWQjaeABiV:matrix.virtual-assembly.org>
+"Reception - our room to chat with visitors"