diff --git a/README.md b/README.md
new file mode 100644
index 0000000..fb21c52
--- /dev/null
+++ b/README.md
@@ -0,0 +1,71 @@
+# Libraire de calcul Jugement majoritaire
+
+Parmi les méthodes de vote le jugement majoritaire est très récent.
+C'est la description de wikipedia https://fr.wikipedia.org/wiki/Jugement_majoritaire qui a servi de référence.
+
+(https://en.wikipedia.org/wiki/Majority_judgment)
+
+L'implémentaion est très basique et miminale :
+
+|langage|code|
+|-----|---------------------|
+|python|code/parse_sample.py|
+|php|code/parse_sample.php|
+
+# Formats des votations ( json )
+
+Le format d'entrée est un fichier json, des exemple sont sous le répertoire samples.
+
+Le format de sortie est aussi un fichier json
+
+## candidats
+
+les candidats ont des clés textuelles courtes, qui peuvent être numérique ou alpjanumérique et un nom complet de candidat.
+
+```
+    "A":"albert",
+    "B":"Beatrice",
+    "C":"Chloé",
+    "D":"Deborah",
+    "E":"Eric",
+    "F":"Francçois",
+    "G":"Gisèle",
+    "H":"Hugo"
+``` 
+
+## votants
+
+Une indication du nombre de votants sert à valider que tous les votes sont bien listés. C'est une information redondante avec la liste des votes de la votation.
+
+    "decompte":10
+
+
+## mentions
+
+La sémantique des mentions est spécifiquer à cahque vote, un texte descriptif indique.
+
+Les mentions sont ordonnées de la mention la meilleure numérotée 0 à la plus mauvaise, la dernière.
+
+|0|Très Bien|
+|1|Bien|
+|2|Assez Bien|
+|3|Passable|
+|4|Insuffisant|
+|5|A rejeter|
+
+## votation
+
+Pour information une date et un lien de vote sont ajoutés.
+Leur contenu est textuel et laissé à l'appréciation de l'utilisateur, le champ n'est pas analysé.
+
+```
+"date":"14 juin 2025",
+"lieu":"liffré",
+```
+
+### votes
+
+le vote est une liste des vote de chaque participant.
+
+chaque vote contient une liste de référence des candidats et le rang de leur mention.
+
diff --git a/samples/parse_sample.php b/code/parse_sample.php
similarity index 100%
rename from samples/parse_sample.php
rename to code/parse_sample.php
diff --git a/samples/parse_sample.py b/code/parse_sample.py
similarity index 100%
rename from samples/parse_sample.py
rename to code/parse_sample.py
diff --git a/samples/check.sh b/samples/check.sh
index 10070cc..cc8a58c 100755
--- a/samples/check.sh
+++ b/samples/check.sh
@@ -22,5 +22,7 @@ then
     json=$json_file
 fi
 
-python3 parse_sample.py $json_file
-php parse_sample.php $json_file
+code_dir=../code/
+
+python3 ${code_dir}parse_sample.py $json_file
+php ${code_dir}parse_sample.php $json_file