Improved documentation

README.md

@@ -1,6 +1,5 @@
 # Assistant RGAA
 
-
 Assistant RGAA est une extension de navigateur pour Firefox et Chrome.
 
 L'extension propose la liste complète des critères et tests du référentiel RGAA 3.0 2016, le référentiel général d'accessibilité pour les administrations de l'État français. Ce référentiel est une adaptation opérationnelle des règles internationales d'accessibilité (WCAG 2.0).

doc/architecture.md

@@ -2,7 +2,7 @@
 
 L'extension se base sur le projet [WebExtensions](https://developer.mozilla.org/en-US/Add-ons/WebExtensions).
 
-Le `manifest.json` décrit la configuration de l'appli et permet d'avoir une vue globale sur quelle partie du code est chargée où.
+Le `manifest.json` décrit la configuration de l'application et permet d'avoir une vue globale sur quelle partie du code est chargée où.
 
 ## Contenu de chaque dossier
 
@@ -29,7 +29,7 @@ Avant de décrire chaque partie (*background*, *common*, etc.), on peut s'attard
 * `/sagas` : les [sagas redux](http://yelouafi.github.io/redux-saga/) à utiliser.
 * `/selectors` : les fonctions permettant de récupérer facilement des données du *state* [redux](http://redux.js.org/)
 
-### partie `/background`
+### Partie `/background`
 
 C'est le code correspondant au *background script* de l'extension. Ici, on :
 
@@ -40,7 +40,7 @@ C'est le code correspondant au *background script* de l'extension. Ici, on :
 
 Un fichier de build `dist/background.js` est généré avec ce code.
 
-### partie `/common`
+### Partie `/common`
 
 C'est la plus grosse partie du code. Ici, on a notamment :
 
@@ -50,7 +50,7 @@ C'est la plus grosse partie du code. Ici, on a notamment :
 
 Aucun fichier de build n'est généré avec ce code : c'est dans chaque partie différente du code qu'on utilise les choses dont on a besoin venant du dossier *common*.
 
-### partie `/container`
+### Partie `/container`
 
 Ce code correspond à un *content-script* de l'extension. Il est injecté dans chaque page que vous chargez. Dans cette partie :
 
@@ -61,7 +61,7 @@ Ce code correspond à un *content-script* de l'extension. Il est injecté dans c
 
 Des fichier de build `dist/container.{js,css}` sont générés avec ce code. Les deux sont injectés dans la page courante.
 
-### partie `/helpers`
+### Partie `/helpers`
 
 Ce code correspond à un *content-script* de l'extension. Il est injecté dans chaque page que vous chargez.
 
@@ -75,7 +75,7 @@ Un *helper* permet d'appliquer, entre autre, des changements de styles sur la pa
 
 Des fichier de build `dist/helpers.{js,css}` sont générés avec ce code. Les deux sont injectés dans la page courante.
 
-### partie `options`
+### Partie `options`
 
 Ce code correspond à la page d'options de l'extension. Ici :
 
@@ -84,7 +84,7 @@ Ce code correspond à la page d'options de l'extension. Ici :
 
 Des fichier de build `dist/options.{js,css}` sont générés avec ce code. Ils sont utilisés dans `/options/content.html` qui est indiqué comme la page d'options dans le `manifest.json` de l'extension.
 
-### partie `panel`
+### Partie `panel`
 
 Ce code correspond au panneau latéral affiché ou caché quand on clique sur le bouton de l'extension.
 
@@ -99,7 +99,7 @@ Les *background script*, *content script*, *option pages* étant tous des élém
 
 * chaque partie du code possède son propre store.
 * chaque store utilise le même set de reducers : autrement dit, chaque store utilise tous les reducers de l'extension.
-* chaque store est créé avec des middleware de synchronisation pour qu'à tout moment, dans tous les stores, on ai les mêmes données. Quand une action est déclenchée dans un des stores, les middleware déclenchent la même action dans les autres stores, avec les mêmes données (grâce aux api de messages des webextensions). Ceci est fait afin que lors des développements, on puisse travailler comme s'il n'y avait qu'un unique store pour toute l'appli.
+* chaque store est créé avec des middleware de synchronisation pour qu'à tout moment, dans tous les stores, on ait les mêmes données. Quand une action est déclenchée dans un des stores, les middleware déclenchent la même action dans les autres stores, avec les mêmes données (grâce aux api de messages des webextensions). Ceci est fait afin que lors des développements, on puisse travailler comme s'il n'y avait qu'un unique store pour toute l'application.
 * dans le *background script*, le store créé est "persistant". Chaque modification sur l'état est sauvegardé dans le *storage local* de l'extension.
-* dans le *panel*, le store créé récupère les données "persistées" venant du store du *background script*. Ceci est fait car, contrairement à toutes les autres parties de l'appli, le panel peut être généré *après* le "démarrage" de l'extension. Si on ouvre le panel dans une popup après l'avoir utilisé 5 minutes, il faut que le panel se souvienne de son état précédent quand il passe dans une nouvelle fenêtre. Il récupère donc un état sauvegardé.
+* dans le *panel*, le store créé récupère les données "persistées" venant du store du *background script*. Ceci est fait car, contrairement à toutes les autres parties de l'application, le panel peut être généré *après* le "démarrage" de l'extension. Si on ouvre le panel dans une popup après l'avoir utilisé 5 minutes, il faut que le panel se souvienne de son état précédent quand il passe dans une nouvelle fenêtre. Il récupère donc un état sauvegardé.
 * la page d'options utilise directement le store du *background script*. Contrairement aux *content script*, la page d'options à accès à l'api webextensions `getBackgroundPage` et peut donc éviter d'avoir un store à synchroniser.

doc/donnees.md

@@ -4,20 +4,20 @@ L'extension permet de travailler avec plusieurs versions du référentiel RGAA.
 
 ## Référentiels
 
-Dans `data/references/`, il y a des fichiers décrivant un référentiel dans une version donnée.
+Dans `data/references/`, on trouve des fichiers décrivant un référentiel dans une version donnée.
 
 Le fichier est nommé en suivant la version. Dans ce fichier est décrit la version du référentiel, et les thématiques, critères et tests du référentiel. Chaque thématique, critère et test a un identifiant unique.
 
-Actuellement, on peut générer les fichiers via des utilitaire qui *scrapent* des page web de référentiel, ou les taper à la main... À l'avenir, à voir si des fichiers "officiels" seront fournis.
+Actuellement, on peut générer les fichiers via des utilitaires qui *scrapent* des page web de référentiel, ou les écrire à la main... À l'avenir, à voir si des fichiers "officiels" seront fournis.
 
 ## Instructions
 
-Dans `data/instructions`, il y a des fichiers décrivant des instructions de test pour une version de référentiel donnée. Les instructions sont propres à l'extension, c'est pourquoi elles ne sont pas décrites directement dans les fichiers de référentiels.
+Dans `data/instructions`, on trouve des fichiers décrivant des instructions de test pour une version de référentiel donnée. Les instructions sont propres à l'extension, c'est pourquoi elles ne sont pas décrites directement dans les fichiers de référentiels.
 
 Le fichier est nommé en suivant la version.
 
 ## Helpers
 
-Dans `data/helpers/`, il y a des fichiers décrivant les helpers à utiliser pour chaque test d'un référentiel d'une version donnée. Voir la doc [Helpers](doc/helpers.md) pour plus de détails.
+Dans `data/helpers/`, on trouve des fichiers décrivant les helpers à utiliser pour chaque test d'un référentiel d'une version donnée. Voir la documentation des [helpers](doc/helpers.md) pour plus de détails.
 
 Le fichier est nommé en suivant la version.

doc/installation-dev.md

@@ -1,10 +1,12 @@
 ## Installation (développement)
 
-Clonez le repo, puis :
+Clonez le dépôt, puis lancez les commandes suivantes :
 
-```
+```sh
 npm install
 npm start
 ```
 
-Chargez ensuite l'extension en suivant directement les docs officielles : dans [Firefox Developer Edition](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox) ou [Chrome 52 et plus](https://developer.chrome.com/extensions/getstarted#unpacked).
+Chargez ensuite l'extension en suivant directement les docs officielles :
+* [Firefox Developer Edition](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox)
+* [Chrome 52 et plus](https://developer.chrome.com/extensions/getstarted#unpacked)

doc/installation.md

@@ -1,39 +1,35 @@
 ## Installation de l'extension sur votre navigateur
 
-Vous avez plusieurs façons différentes de faire pour installer l'extension
+Vous pouvez installer l'extension de différentes façons.
 
 *Note : pour voir comment installer l'extension afin de contribuer à son développement, voir la doc [Installation (développement)](doc/installation-dev.md).*
 
-### Installer depuis le Chrome Web Store
-
-Sur Chrome, vous pouvez installer l'extension directement depuis le Chrome Web Store : https://chrome.google.com/webstore/detail/rgaa-toolbar/cgpmofepeeiaaljkcclfldhaalfpcand
-
 ### Installer depuis un un fichier zip ou xpi
 
 * sur Chrome (version 52 et plus) :
-    * Sur le projet Gitlab, allez dans *Repository > Tags* et téléchargez le fichier **zip** correspondant à la version souhaitée.
-    * faites un drag&drop du fichier zip sur la page *chrome://extensions* : l'extension apparait (si y'a un message en rouge dans la description de l'extension, ce n'est pas grave)
-    * S'il y a une erreur, essayez d'extraire le zip d'abord, puis de drag&drop le dossier extrait.
-    * ouvrez un nouvel onglet pour pouvoir utiliser l'extension dessus
-    * si au bout de quelques minutes, heures ou jours, Chrome désactive l'extension par sécurité, essayez d'installer l'extension via la méthode développeur](#installer-en-mode-d%C3%A9veloppeur)
+    * Sur le projet GitHub, allez sur [la liste des versions](https://github.com/DISIC/assistant-rgaa/releases) et téléchargez le fichier `.zip` correspondant à la version souhaitée.
+    * faites un glisser-déposer du fichier `.zip` sur la page [chrome://extensions](chrome://extensions) : l'extension doit apparaitre dans la liste (si un message en rouge apparaît dans la description de l'extension, ce n'est pas grave)
+    * S'il y a une erreur, essayez d'extraire le fichier `.zip` d'abord, puis de glisser-déposer le dossier extrait.
+    * ouvrez une nouvelle page web pour pouvoir utiliser l'extension dessus
+    * si au bout de quelques minutes, heures ou jours, Chrome désactive l'extension par sécurité, essayez d'installer l'extension via la méthode développeur (voir ci-dessous)
 * sur Firefox (version 52 et plus) :
-    * Sur le projet Gitlab, allez dans *Repository > Tags* et téléchargez le fichier **xpi** correspondant à la version souhaitée. Si vous n'êtes pas sûr, prenez la version la plus récente.
-    * faites un drag&drop du fichier sur n'importe quel onglet ouvert sur Firefox : une boîte de dialogue apparait, vous demandant si vous voulez installer l'extension.
-    * redémarrez firefox et ouvrez un nouvel onglet pour pouvoir utiliser l'extension dessus
+    * Sur le projet GitHub, allez sur [la liste des versions](https://github.com/DISIC/assistant-rgaa/releases) et téléchargez le fichier `.xpi` correspondant à la version souhaitée. Si vous n'êtes pas sûr, prenez la version la plus récente.
+    * faites un glisser-déposer du fichier sur n'importe quel onglet ouvert sur Firefox : une boîte de dialogue apparait, vous demandant si vous voulez installer l'extension.
+    * redémarrez firefox et ouvrez une nouvelle page web pour pouvoir utiliser l'extension dessus
 
 ### Installer en mode développeur
 
-* Sur le projet Gitlab, allez dans *Repository > Tags* et téléchargez le fichier **zip** correspondant à la version souhaitée. Si vous n'êtes pas sûr, prenez la version la plus récente.
+* Sur le projet GitHub, allez sur [la liste des versions](https://github.com/DISIC/assistant-rgaa/releases) et téléchargez le fichier `.zip` correspondant à la version souhaitée. Si vous n'êtes pas sûr, prenez la version la plus récente.
 * extrayez l'archive où bon vous semble sur votre machine
 * sur Chrome (version 52 et plus) :
-    * allez sur la page *chrome://extensions* et activez le "Mode développeur" (case en haut à droite)
+    * allez sur la page [chrome://extensions](chrome://extensions) et activez le "Mode développeur" (case en haut à droite)
     * cliquez sur le nouveau bouton "Charger l'extension non empaquetée..."
-    * sélectionnez le dossier que vous venez d'extraire. Ce dossier contient les dossiers *bin*, *css*, *data*, *dist*, etc.
+    * sélectionnez le dossier que vous venez d'extraire. Ce dossier contient les dossiers `bin/`, `css/`, `data/`, `dist/`, etc.
     * l'extension apparait !
-    * ouvrez un nouvel onglet pour pouvoir utiliser l'extension dessus
+    * ouvrez une nouvelle page web pour pouvoir utiliser l'extension dessus
 * sur Firefox (version 52 et plus) :
-    * allez sur la page *about:addons*, cliquez sur la roue en haut à droite, puis sur "Deboguer des modules"
-    * sélectionnez le fichier *manifest.json* contenu dans le dossier que vous avez extrait
+    * allez sur la page [about:addons](about:addons), cliquez sur la roue en haut à droite, puis sur "Deboguer des modules"
+    * sélectionnez le fichier `manifest.json` contenu dans le dossier que vous avez extrait
     * l'extension apparait !
-    * ouvrez un nouvel onglet pour pouvoir utiliser l'extension dessus
-    * :warning: l'extension n'est chargée que pour la session actuelle ; fermer le navigateur désinstallera l'extension
+    * ouvrez une nouvelle page web pour pouvoir utiliser l'extension dessus
+    * :warning: l'extension n'est chargée que pour la session actuelle; fermer le navigateur désinstallera l'extension

doc/publication.md

@@ -2,33 +2,32 @@
 
 ## 1. Augmenter le n° de version
 
-Avant de construire la build, n'oubliez pas de changer la version de l'appli dans le package.json et le manifest.json.
+Avant de construire la build, n'oubliez pas de changer la version de l'application dans `package.json` et `manifest.json`.
 
 ## 2. Taguer
 
 N'oubliez pas de taguer, sur master, l'état de l'application avec le nouveau n° de version.
 
 ## 3. Construire la build
 
-À la racine du projet, lancer
+À la racine du projet, lancez
 
-```
-./bin/build [--api-key clé --api-secret secret]
+```sh
+./bin/build --api-key CLE --api-secret SECRET
 ```
 
 Cette commande fait plusieurs choses :
 
-* elle construit une branche locale *publication*
+* elle construit une branche locale `publication`
 * elle ajoute en *staging* dans le dossier `/dist` les sources buildées : js, css, svg
-* elle ajoute en *staging* dans le dossier `/artifacts` un fichier zip contenant l'extension . Ce fichier peut être uploadé sur le store Chrome pour publication. Il peut aussi être utilisé pour installer l'extension à la main en local, sur Chrome et Firefox.
-* **si les clés d'API sont renseignées**, elle ajoute en *staging* dans le dossier `/artifacts` un fichier xpi contenant l'extension. Ce fichier peut être uploadé sur le store Firefox pour publication.
+* elle ajoute en *staging* dans le dossier `/artifacts` un fichier `.zip` contenant l'extension, pouvant être uploadé sur le store Chrome pour publication. Il peut aussi être utilisé pour installer l'extension à la main en local, sur Chrome et Firefox.
+* **si les clés d'API sont renseignées**, elle ajoute en *staging* dans le dossier `/artifacts` un fichier `.xpi` contenant l'extension. Ce fichier peut être uploadé sur le store Firefox pour publication.
 
-Les paramètres `--api-key` et `--api-secret` renseignent les clés publiques et privées associées au compte qui publie l'extension (voir https://developer.mozilla.org/en-US/Add-ons/WebExtensions/web-ext_command_reference#web-ext_sign). Demandez à Félix les clés pour l'instant !
+Les paramètres `--api-key` et `--api-secret` renseignent les clés publiques et privées associées au compte qui publie l'extension (voir https://developer.mozilla.org/en-US/Add-ons/WebExtensions/web-ext_command_reference#web-ext_sign).
 
-**La commande ne commit et ne push rien, c'est à vous de le faire**. Quand vous vous dites que tout est OK, commitez les fichiers buildés sur votre branche publication locale, et remplacez celle distante par la votre :
+**La commande ne commit et ne push rien, c'est à vous de le faire**. Quand tout est vérifié, commitez les fichiers buildés sur votre branche publication locale, et remplacez celle distante par la votre :
 
-```
-git commit -m "new build"
+```sh
+git commit -m "New build"
 git push -f origin publication
 ```
-