Commit 263b751f authored by Bertille Dubosc de Pesquidoux's avatar Bertille Dubosc de Pesquidoux
Browse files

Corrections de la doc

parent 81bbd28f
......@@ -37,7 +37,7 @@ Après un petit temps de chargement, un éditeur en ligne s'ouvre. Vous pouvez a
[URL du fichier]
```
Quand vous avez fini, cliquez sur le bouton bleu « Commit... » en bas à gauche. Vérifiez que la case « Start a new merge request » est bien cochée et validez en cliquant à nouveau sur le bouton, qui est devenu vert.
Quand vous avez fini, cliquez sur le bouton bleu « Commit... » en bas à gauche. Vérifiez que la case « Start a new merge request » (c'est-à-dire, [une demande de prise en compte de vos ajouts](https://docs.gitlab.com/ee/user/project/merge_requests/getting_started.html)) est bien cochée et validez en cliquant à nouveau sur le bouton, qui est devenu vert.
La page qui s'ouvre est l'interface pour saisir une demande d'intégration de vos modifications dans le projet principal. Donnez-lui un titre explicite, comme par exemple « Ajout du Chaton X » et cliquez sur « Submit merge request »
......
# Une liste de ce qui ne sera pas achevé
Le temps de la est terminé et un certain nombre de chantiers sont encore en cours. Nous les listons ici pour qu'ils ne soient pas oubliés.
## Sur le schéma
* À l'heure actuelle, les valeurs sont des étiquettes en français approximatif. Par exemple, une des valeurs possibles pour le type de service est : `partage_temporaire_fichier`. Il serait plus pertinent de choisir soit une étiquette en anglais (`temporary_file_sharing`), soit directement la donnée en français (`Partage temporaire de fichiers (alternative à WeTransfer, DropSend)`) comme c'est le cas dans [les fiches de chatons.org](https://entraide.chatons.org/page-data/fr/page-data.json).
Une synthèse sur cette réflexion est disponible [à la page suivante](formatage_donnees.md) et pourrait aboutir à une version 0.0.3 du schéma (ou même à une 0.1 ?).
* Le schéma actuel n'est pas exhaustif. Certaines informations des fiches des Chatons, qui ne sont pas forcément nécessaires à l'utilisateur·ice final·e mais sont utiles à la vie du collectif, manquent. Par exemple, le schéma ne permet pas pour l'instant de détailler le respect de la charte point par point.
* De façon générale, la modélisation est amenée à évoluer en même temps que le collectif.
## Sur la conversion
* Pour l'instant, on ne peut convertir les données récoltées qu'au format d'entraide.chatons.org. Il serait intéressant de pouvoir exporter les données dans le format Organization de schema.org, pour accéder à l'interopérabilité du web sémantique. Le sujet est détaillé [dans cette section](jsonld.md).
* On pourrait imaginer encore d'autres formats d'export, et donc de rendre la conversion plus modulable. Est-il possible d'adapter le script existant en ce sens, ou vaut-il mieux repartir d'un autre outil ? La question est ouverte. En tout cas, l'outil de conversion pourrait gagner en clarté.
## Sur le crawler
* Pour l'instant, le crawler utilise un module de logging maison. Il faudrait plutôt utiliser le module natif de Python, et donc passer du temps à examiner quel comportement est souhaité et comment l'obtenir.
* De manière générale, le code pourrait être plus propre.
## Sur le site
* Le site mériterait un coup de CSS pour être plus joli s'il doit être gardé, ou d'être intégré à chatons.org sinon.
* [L'outil de recherche](http://chatons.picasoft.net/search/recherche.html), en particulier, n'est pas très convivial et ne permet pas d'interroger tous les champs.
* [L'outil de génération de fiche](<http://chatons.picasoft.net/gen/json_gen.html>) pourrait être refait maison.
## Sur le passage au collectif
* Pour l'instant, tout est sur un Framagit personnel mais le but est de laisser la main au CHATONS si la preuve de concept séduit. Dans ce cas, il faudrait tout transférer sur [le groupe du collectif](http://chatons.picasoft.net/gen/json_gen.html), s'assurer que la documentation est suffisante et rester disponibles. La question de l'intégration technique et fonctionnelle à https://chatons.org reste à imaginer.
......@@ -37,10 +37,11 @@ Inconvénients
Avantages
- Le site actuel du CHATONS utilise une BDD PostgreSQL, cela ne duplique pas l'infrastructure technique.
- Depuis la version 9.2, il est possible de créer des colonnes avec un type JSON, et donc de travailler facilement avec nos données.
Inconvénients
- C'est une BDD relationnelle. Les colonnes peuvent facilement avoir un type JSON mais il sera sans doute préférable de travailler un peu l'export pour en faire quelque chose de plus dans la philosophie des tables.
- Ce reste un système plus lourd à mettre en place puisqu'il faut faire appel à un serveur de base de données.
Question de l'intégration technique et fonctionnelle au site du CHATONS
=========================================================================
......
# Un outil pour créer plus facilement la fiche d'un Chaton
Une fiche d'un Chaton ressemble à ça :
```json
{
"name": "Picasoft",
"description": "L’Association Picasoft a pour objet de promouvoir et défendre une approche libriste respectueuse de la vie privée et de la liberté d’expression dans le domaine de l’informatique.",
"url": "https://picasoft.net",
"logo": "https://doc.picasoft.net/res/picasoft_logo_alt.png",
"structure": "association",
"status": "approuve",
"servers": [ "https://tetaneutral.net/" ],
"economic_model": [ "don", "adhesion", "subvention", "autre" ],
"public": [ "tou.te.s", "adherent.e.s" ],
"creation_date": "2016",
"address": "rue Roger Couttolenc, 60200 Compiegne",
"perimeter": "Oise",
"services": [
{
"type": "messagerie_instantanee",
"description": "Instance Mattermost pour communiquer en équipe",
"url": "https://team.picasoft.net",
"software": "mattermost",
"account": "sur_inscription",
"public": "tou.te.s",
"price": "gratuit",
"degradability": 0,
"weight": 5
}
]
}
```
Pour éviter de devoir écrire un tel fichier à la main, nous avons mis en place un [générateur de fiche](http://chatons.picasoft.net/gen/json_gen.html).
C'est en fait un formulaire qui est lui-même généré automatiquement à partir du [schéma](schema.md) grâce à la librairie [json-forms](https://github.com/brutusin/json-forms) développée par [Brutusin](https://brutusin.org).
La librairie est appelée grâce à un bout de code en JavaScript inséré dans la [page du générateur](https://framagit.org/bertille/tx-collecte-chatons/-/blob/master/site/gen/json_gen.html).
......@@ -10,7 +10,9 @@ La convention que nous avons choisie en début de projet [a ses faiblesses](form
## Le schéma
Pour ce faire, nous avons créé un *schéma*, lui aussi exprimé en langage JSON, qui explique quel champ est à utiliser pour quoi, et qui permet de *valider* un JSON décrivant un Chaton, garantissant que l'information est correctement formatée et sera utilisable par l'outil de recheche.
[Le schéma en question](https://framagit.org/bertille/tx-collecte-chatons/-/blob/master/schema/CHATONS_schema-0.0.2.json) indique par exemple qu'un fichier JSON décrivant un Chaton est valide s'il a un champ `name`, `url`, `status` et `structure`, que s'il propose des services alors ces derniers ont un champ `type` et éventuellement une `description`...
La version actuelle du schéma est la [0.0.2](https://framagit.org/bertille/tx-collecte-chatons/-/blob/master/schema/CHATONS_schema-0.0.2.json). Cette information est précisée dans le champ `$id`. Ce champ permet de renseigner l'identifiant unique du schéma, avec notamment sa version, afin d'avoir des données plus cohérentes. C'est une pratique mentionnée dans le [guide officiel des schémas JSON](https://json-schema.org/understanding-json-schema/basics.html#declaring-a-unique-identifier).
[Notre schéma](http://chatons.picasoft.net/schema/schema.json) indique par exemple qu'un fichier JSON décrivant un Chaton est valide s'il a un champ `name`, `url`, `status` et `structure`, que s'il propose des services alors ces derniers ont un champ `type` et éventuellement une `description`...
Pour commencer à décrire votre Chaton, un [template](https://framagit.org/bertille/tx-collecte-chatons/-/blob/master/schema/exemples/template.json) vide est disponible sur le Framagit, ainsi que quelques [exemples](https://framagit.org/bertille/tx-collecte-chatons/-/tree/master/schema/exemples).
......
......@@ -8,8 +8,8 @@ theme:
language: fr
nav:
- Home: 'index.md'
- About:
- 'À propos du projet': 'about.md'
- 'À propos':
- 'Le projet': 'about.md'
- 'Ce site': 'site.md'
- 'Choix techniques':
- 'Centralisation des données': 'centralisation.md'
......@@ -17,8 +17,10 @@ nav:
- 'Contribuer': 'contribuer.md'
- 'Fonctionnement':
- 'Le schéma': 'schema.md'
- 'Le générateur de fiche': 'generation_fiches.md'
- 'Le crawler': 'crawler.md'
- 'Le convertisseur': 'convertisseur.md'
- 'Améliorations':
- 'Feuille de route': 'evolutions_futures.md'
- 'Formalisme du schéma': 'formatage_donnees.md'
- 'Export en JSON-LD': 'jsonld.md'
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment