User guide for accessing the Matrix server

of Assemblée Virtuelle

Needs to be reviewed and validated.

3 files changed, 232 insertions, 0 deletions

diff --git a/Riot_Tools1.png b/Riot_Tools1.png
new file mode 100644
index 0000000..317cf7c
--- /dev/null
+++ b/Riot_Tools1.png
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"
diff --git a/USAGE_GUIDE.fr.md b/USAGE_GUIDE.fr.md
new file mode 100644
index 0000000..9e594bd
--- /dev/null
+++ b/USAGE_GUIDE.fr.md
@@ -0,0 +1,116 @@
+# Guide d'utilisation
+
+> v0.2 (16 nov 2018)
+
+## Introduction
+
+**Matrix** héberge désormais les discussions de la communauté de l'Assemblée Virtuelle, en remplacement de Slack. Un serveur Matrix est auto-hébergé sur le serveur de l'association, et répond au nom de domaine **matrix.virtual-assembly.org**.
+
+Le principe de Matrix repose sur une juxtaposition de « salons », répartis sur une *fédération de serveurs* et qui sont tous indépendants les uns des autres (et non hiérarchisés). Ces salons peuvent être regroupés au sein de **communautés**<sup>1</sup> (*groupes*) qui agissent comme des filtres sur l'ensemble des salons de la fédération Matrix. Un salon peut appartenir à plusieurs communautés. A chaque communauté correspond au moins un salon qui porte le même nom.
+
+Ainsi existe une communauté **General**, qui comprend à ce jour deux salons : *General* et *Reception*.
+
+## Outils d'accès aux salons
+
+Pour accéder aux conversations de la fédération Matrix (et plus particulièrement dans notre cas de l'Assemblée Virtuelle) vous pouvez soit :
+
+1. Utiliser l'interface web à l'adresse suivante :
+[Communauté Assemblée Virtuelle]. Vous arriverez alors sur une page présentant les salons de la communauté **General**.
+1. Utiliser un logiciel client, dont il existe une liste accessible sur cette page : [Matrix clients]. Pour notre part, nous recommandons [Riot] qui est disponible à la fois comme application de bureau et mobile. C'est actuellement l'application la plus mature pour accéder à Matrix. Comme vous le constaterez l'interface web elle-même utilise Riot.
+
+Pour pouvoir accéder aux discussions de la communauté, il est nécessaire d'avoir un compte sur **Matrix**, peu importe le serveur sur lequel vous êtes inscrit. Attention, toutefois, votre expérience utilisateur pourrait être différente en fonction de votre compte (cf. Configuration)
+
+## Création de compte
+
+*Ce qui suit concerne Riot. Les autres clients ne sont pas documentés ici pour l'instant.*
+
+Lorsque vous voudrez rejoindre une communauté ou accéder à un salon,  il vous sera demandé de créer un compte, à moins que vous ne soyez déjà inscrit quelque part sur le réseau Matrix, .
+
+L'instance de l'Assemblée Virtuelle n'est pas publique. La première chose à vérifier pour créer un compte, c'est que vous êtes connu de l'équipe sysadmin de l'Assemblée. Si vous étiez sur Slack, ou que vous êtes de puis longtemps au contact de l'Assemblée, il est probable que ce soit le cas. Sinon, adressez-vous à quelqu'un de l'Assemblée que vous connaissez, afin qu'il avertisse l'équipe sysadmin que vous êtes autorisé à avoir accès aux salons de l'Assemblée Virtuelle<sup>2</sup>. Vous recevrez très rapidement une notification pour créer votre compte.
+
+Suivant la page sur laquelle vous êtes, vous pouvez voir deux invitations différentes. La différence entre « **Rejoindre la communauté** » et « **Rejoindre le salon** » est que, dans le premier cas, vous verrez apparaître l'icône de la communauté dans la colonne latérale à l'extrême gauche de la fenêtre. Vous pouvez faire partie d'autant de communautés que vous le souhaitez et celles-ci vous sépareront visuellement les salons selon différents domaines d'intérêt.
+
+Pour le reste, la procédure d'inscription est la même dans les deux cas.
+
+> **Attention** : sur l'interface web, vous verrez apparaître une fenêtre « pop-up » ; cliquez alors sur « *sélectionner un autre serveur* »
+
+Pour créer un compte, remplissez le formulaire ainsi :
+1. Indiquer votre adresse éléctronique<sup>3</sup>, mais...
+1. **... ne remplissez pas le champ Téléphone** (ceci cause un bug).
+1. Choisissez un pseudonyme et un mot de passe
+1. Avant de cliquer sur **S'inscrire** :
+  1. Vous devez choisir le serveur qui hébergera votre compte ->
+    * le **Serveur par défaut** est sur le domaine https://matrix.org
+    * le **Serveur personnalisé**, celui de l'Assemblée Virtuelle (nous vous conseillons fortement de choisir cette option).
+  1. Pour l'URL du service d'accueil, indiquez : https://matrix.virtual-assembly.org
+  1. Pour l'URL du serveur d'identité, laissez la valeur par défaut : https://riot.im
+  1. Choisissez la langue de l'interface
+1. Vous pouvez maintenant cliquer sur **S'inscrire**
+
+Remplir le formulaire en donnant votre adresse électronique indique votre appartenance (ou non) à l'Assemblée Virtuelle (les adresses ont été reprises depuis Slack).
+
+Une fois connecté, vous pouvez rejoindre les différents salons, dont les icônes s'ajouteront dans la colonne de gauche et que vous pouvez ensuite trier par priorité.
+
+Les identifiants des salons et des communautés sont normalisés comme suit :
+
+|--------------|--------------------------------------------|
+| salon        | #{nom du salon}:{serveur de chat}          |
+|--------------|--------------------------------------------|
+| communauté   | +{nom de la communauté}:{serveur de chat}  |
+|--------------|--------------------------------------------|
+
+Ainsi le salon **Ontologies** a pour identifiant :
+> #ontologies:matrix.virtual-assembly.org
+
+Pour y accéder depuis le web, il faut ajouter le radical
+**https://riot.im/app/#** suivi de **/group** ou **/room** selon les cas.
+> e.g. : https://riot.im/app/#/room/#ontologies:matrix.virtual-assembly.org
+
+## Interface
+
+### Barre d'Outils
+
+En bas à gauche de la fenêtre de Riot, vous trouvez une barre d'outils qui vous permet, de gauche à droite
+
+![Barre d'outils](Riot_Tools1.png "Outils")
+
+- Ajouter une communauté à la liste existante
+- Revenir sur la page d'accueil de Riot
+- Entamer une discussion personnelle avec une personne<sup>4</sup>
+- Afficher le répertoire des salons
+- Créer un nouveau salon
+- Paramètres de votre profil personnel
+
+> **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.
+
+## Utilisation
+
+### Mentions
+- Pour mentionner une personne dans une conversation, insérez l'annotation "@pseudo_de_la_personne" (comme dans Slack)
+- Vous pouvez mentionner toutes les personnes inscrites sur le salon avec l'annotation "@room".
+- Vous pouvez mentionner un (autre) salon dans une conversation en faisant précéder son nom d'un croisillon "#".
+- Vous pouvez faire mention d'un communauté dans une conversation en préfixant son nom avec le signe “+”.
+
+## Bonnes pratiques
+
+1. Ne laissez pas votre avatar vide, et mettez une image facilement discernable.
+
+## Notes
+1. « communauté » est le terme utilisé par Riot, alors que Matrix définit des « groupes »
+1. La procédure doit encore être validée
+1. Si vous déjà étiez inscrit sur Slack, veillez à reprendre l'adresse électronique que vous y utilisez.
+1. L'équivalent des messages directs de Slack.
+
+
+
+[Communauté Assemblée Virtuelle]: <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"