Reorganisation de la documentation technique (#1155)

docs/README.md

@@ -2,24 +2,59 @@
 
 ## Par ou commencer ?
 
-_Description à venir ici_
+Cette documentation aide les développeurs et toute personne s'intéressant à la construction technique de la plateforme à comprendre son architecture, son fonctionnement et les prises de décision qui y ont abouties.
+
+Elle est répartie en 4 sections suivant la convention [DIATAXIS](https://diataxis.fr)
+
+![](https://diataxis.fr/_images/diataxis.png)
+
+Pour en savoir plus sur la construction de cette documentation, suivez le guide : [Guide de la documentation technique](./reference/901-documentation-technique.md)
 
 ## Référence
 
-- [Docmentation technique](./reference/Documentation-technique.md)
-- [Règles de codage](./reference/Coding-guidelines.md)
-- [Règle de codage de la base de données](./reference/DB-guidelines.md)
-- [Architecture des fichiers de code de la partie data](./reference/Organisations-des-fichiers-data.md)
-- [Frontend et templating](./reference/Frontend.md)
+Contient toute la description technique de l'application, par exemple :
+
+- Architecture des fichiers
+- Architecture des données
+- Conventions de code et de base de données
+…
 
 ## Explications
 
-_Nouvelle rubrique ici bientôt_
+Description de comment ça marche et des prises de décision, par exemple :
+
+- Pourquoi ce choix d'architecture des données
+- Principe sanitaire mise en place sur la platefome données
+…
 
 ## Comment faire ?
 
-- [Commandes Django utiles](./comment-faire/Commandes-Django.md)
+Guide l'utilisateur pour résoudre un problème, par exemple :
+
+- Copie de la base de données de prod vers preprod
+- Debugage
+…
 
 ## Tutoriels
 
-_Nouvelle rubrique ici bientôt_
+Décrit les apprentissages pas à pas de l'utilisation des outils, par exemple
+
+- Installation d'un poste développeur
+- Mise en production
+…
+
+## Sommaire
+
+- [🧐 REFERENCE](./reference/README.md)
+  - [Règles de codage](./reference/101-coding-guidelines.md)
+  - [Frontend et templating](./reference/201-frontend.md)
+  - [Règle de codage de la base de données](./reference/301-db-guidelines.md)
+  - [Architecture des fichiers de code de la partie data](./reference/302-organisations-des-fichiers-data.md)
+  - [Guide de la docmentation technique](./reference/901-documentation-technique.md)
+
+- [❓ EXPLICATIONS](./explications/README.md)
+
+- [🤔 COMMENT FAIRE ?](./comment-faire/README.md)
+  - [Commandes Django utiles](./comment-faire/101-commandes-django.md)
+
+- [🙌 TUTORIELS](./tutoriels/README.md)

docs/comment-faire/README.md

@@ -0,0 +1 @@
+# 🤔 COMMENT FAIRE

docs/explications/README.md

@@ -0,0 +1 @@
+# ❓ EXPLICATIONS

docs/reference/Organisations-des-fichiers-data.md → docs/reference/302-organisations-des-fichiers-data.md

@@ -2,7 +2,7 @@
 
 Appliqué plus spécifiquement lors de la réorganisation des fichiers des dags d'ingestion des sources
 
-```
+```txt
 /dags
 |- config
 |- source                           -> fichiers spécifique à l'ingestion des sources

docs/reference/901-documentation-technique.md

@@ -0,0 +1,67 @@
+# Guide de la docmentation technique
+
+La documentation technique est entretenue dans le code, dans le dossier [docs](./)
+
+Elle suit la convention [DIATAXIS](https://diataxis.fr) et met en application, tant que faire se peut, les guidelines de documentation définies par [Google](https://developers.google.com/style)
+
+![Organisation de la documentation selon diataxis](https://diataxis.fr/_images/diataxis.png)
+
+## TL;PL : Diataxis
+
+On découpe la documentation en 4 parties:
+
+- TUTORIELS : Apprentissage pas à pas de l'utilisation de l'outil, ex : installer l'application sur un poste de développeur ([docs/tutoriels](../tutoriels/README.md))
+- COMMENT-FAIRE : Guide l'utilisateur pour résoudre un problème, ex : copie de la base de données de prod vers preprod ([docs/comment-faire](../comment-faire/README.md))
+- EXPLICATIONS : Description de comment ça marche et des prises de décision, ex : architecture des données Acteurs et de leur revision ([docs/explications](../explications/README.md)))
+- REFERENCE : Description technique, ex : Architecture du dossier `data` ([docs/reference](../reference/README.md))
+
+## Spécificité de la documentation du projet
+
+Pour toute affirmation dans la documentation, il est possible d'ajouter un `Statut` qui décrit si la décision est appliquée.
+
+- ❓ À approuver : l'équipe technique doit approuver la documentation avant de l'appliquer
+- 🔄 En cours d'application : la proposition a été adoptée, et doit être appliquée pour tout futur développement
+
+Si aucun statut n'est précisé, la documentation est valide et appliquée.
+
+Une documentation refusée par l'équipe sera supprimée
+
+Chaque modification de code qui désapprouve la documentation doit faire l'objet d'une modification de la documentation qui doit être approuvée en réunion de développeurs ou directement via la _pull request_.
+
+## Publication
+
+**Statut : ❓ À approuver**
+
+La documentation devra être propulsée par une bibliothèque de publication de documentation, à définir.
+
+Candidats:
+
+- Docsify (JS)
+- Sphinx (python) - A priori, la solution préférée à ce jour
+
+## Convention
+
+**Statut : ❓ À approuver**
+
+### Liens vers les fichiers
+
+On fera attention d'utiliser les chemins complets vers les fichiers cibles pour une compatibilité de navigations dans les éditeurs tels que vscode et dans l'interface github.com. Parmi les chemins suivants, on n'autorisera que le format whitelisté (✅):
+
+- `[chemin vers le README.md du dossier](./<dossier>/README.md)` ✅
+- `[chemin vers le README.md du dossier](/<dossier>/README.md)` ❌
+- `[chemin vers le README.md du dossier](./<dossier>/)` ❌
+- `[chemin vers le README.md du dossier](/<dossier>/)` ❌
+
+### Règles de nommage des fichiers dans un dossier
+
+Pour garantir l'ordre d'apparition des fichiers dans la barre de défilement à gauche, on préfixe le fichier par un numéro de 3 chiffres qui détermine l'ordre d'apparition dans le menu
+
+On groupera les sujets grâce au chiffre des centaines, puis des dizaines, et enfin on ordonnera les sous rubriques dans la barre de défilement latérale par ordre croisant des noms de fichiers
+
+Ex : dans le dossier REFERENCE
+
+- 101-coding-guidelines.md : en 1xx, les règles générales
+- 201-frontend.md : en 2xx les règles frontend
+- 311-db-guidelines.md : en 3xx les règles de données, 31x relatif à la base de données
+- 322-organisations-des-fichiers-data.md : 32x relatif à la plateforme data
+- 901-documentation-technique.md : 9xx les règles de documentation, volontairement en 9xx pour qu'elle soient affichées à la fin de la section

docs/reference/README.md

@@ -0,0 +1 @@
+# 🧐 REFERENCE

docs/tutoriels/README.md

@@ -0,0 +1 @@
+# 🙌 TUTORIELS