Qu’est-ce que c’est ?
Vous n’avez pas entendu parlé d’Open Know How ? Non vraiment ? En fait c’est normal, c’est tout beau tout neuf (2019) !
Alors pourquoi en parler ?
Parce que Open Know How est une tentative de formalisation d’un standard permettant d’échanger des projets de fabrication. Rien que ça ! Il y a déjà eu quelques tentatives, mais ça n’a pas vraiment marché. Alors que là, avec Open Know How, la sauce commence à prendre, près de 400 projets sont déjà référencés sur la liste sur Github, avec le soutiens de plusieurs associations (dont e-nable) et plusieurs universités
Combien de fois êtes vous tombé sur des tutos ou des sites pour makers où chaque site a son propre mode pour détailler les projets ? Il manque souvent des choses : sources, liens, fichiers, références à des projets similaires ou évolutions de projets antérieurs. L’objectif d’Open Know How est de créer des règles pour décrire ces projets et permettre leur interopérabilité et faciliter les échanges.
Open Know How prévoit 3 niveaux de maturité pour le standard :
- Niveau 1 : permettre la découverte et la recherche de projets (on parle des moteurs de recherche là).
- Niveau 2 : fournir un format et une structure de description des projets pour permettre leurs échanges.
- Niveau 3 : créer une plate-forme distribuée qui permette l’échange des projets de manière décentralisée. Une sorte de google qui ne référencerait que des projets open-hardware.
Pour l’instant on en est au niveau 2 de maturité. Le schéma pour déclarer un projet a été arrêté même s’il continue d’évoluer. Une solide base qui fait consensus a déjà été acceptée. C’est ce schéma de déclaration que nous allons voir en détail, afin que vous puissiez commencer à documenter vos projets et faciliter leur découverte sur les moteurs de recherche.
Comment créer une fiche projet pour Open Know How ?
Nous allons apprendre comment construire la fiche de son projet, valider cette fiche pour s’assurer qu’elle respecte le standard et enfin rajouter l’adresse de votre projet à la liste des projets déjà déclarés.
YAML kesako ?
Mais avant de commencer, il va nous falloir nous familiariser avec YAML (YAML Ain’t Markup Language : « YAML n’est pas un langage de balisage »). Pourquoi ça? Parce que la déclaration d’une fiche projet pour Open Know How se fait en YAML. Pas de panique, c’est très simple !
Vous connaissez sans-doute le format de fichier .CSV ? Ce fichier au format texte qui liste des données séparées par un séparateur (virgule(,), point-virgule(;), pipe (|)…). La première ligne servant à identifier le type de donnée. Cela peut donner quelque chose du type :
Ref. Produit;Nom Produit;Prix;Stock;Date dispo 038414;Raspberry Pi 1A;15€;4;20130215 038415;Raspberry Pi 1A+;16€;7;20131109 [...]
Pas facile à lire hein ? Et bien YAML a pour objectif de pouvoir décrire des données structurée tout en restant lisible. YAML s’inspire du XML en plus simple et permet même d’inclure d’autres syntaxes comme le JSON.
En XML, le fichier CSV précédent pourrait donner quelque chose comme :
<liste_produits>
<produit>
<ref_produit>038414</ref_produit>
<nom_produit>Raspberry Pi 1A</nom_produit>
<prix>15€</prix>
<stock>4</stock>
<date_dispo>20130215</date_dispo>
</produit>
<produit>
<ref_produit>038415</ref_produit>
<nom_produit>Raspberry Pi 1A+</nom_produit>
<prix>16€</prix>
<stock>7</stock>
<date_dispo>20131109</date_dispo>
</produit>
</liste_produits>
En YAML ce même fichier pourrait donner quelque chose comme :
--- # Liste produits - Ref produit : 038414, Nom produit : Raspberry Pi 1A, Prix : 15€, Stock : 4, Date dispo : 20130215 - Ref produit : 038415, Nom produit : Raspberry Pi 1A+, Prix : 16€, Stock : 7, Date dispo : 20131109
Tout de suite c’est beaucoup plus facile à lire, non ? Ce qu’il faut savoir c’est que YAML est sensible à la casse des caractères (« Prix » et « prix » ne représenteront pas la même chose) et à l’indentation du fichier (comme pour python).
Mais comme on va vous donner un modèle de document à la fin de cette page, vous n’aurez véritablement qu’à remplacer les contenus par les vôtres, tout simplement !
Le fichier du projet
il doit s’écrire : okh-nom-du-projet.yml par exemple :
okh-recto-cube.yml
Si vous utilisez des urls vers d’autres fichiers (images etc.) dans le fichier, vous pourrez soit utiliser des urls avec un chemin absolu (https://…) soit un chemin relatif par rapport à la position du fichier okh-xxx.yml que vous aurez créé.
Les # servent à faire des commentaires dans le format du fichier.
Dernière chose très importante : le fichier doit être encodé au format UTF-8 (normalement c’est le standard maintenant, mais bon on trouve encore de l’ISO-8859-1 parfois alors…).
Comme exemple vous pouvez regarder mon fichier okh-recto-cube.yml sur notre projet de Recto-cube sur Github
Le modèle du fichier
Le modèle est disponible en anglais sur cette page et tous les éléments qui peuvent y être ajoutés y sont également décrits. Vous pouvez aussi télécharger notre version en français ici.
Valider son fichier
Une fois votre fichier créé, il est important de valider son schéma à l’aide d’un validateur. Simplement copiez-collez le contenu dans la zone de gauche du validateur et passez en revue les vérifications ou éventuelles corrections dans la zone de droite.
Si le format YAML n’est pas correct, vous pourrez toujours valider le code sur le validateur Lint de YAML.
Rajoutez votre projet à la liste existante
Pour l’instant les moteurs de recherche ne sont pas paramétrés pour chercher et lire les fichiers .okh, mais cela va venir (c’est la prochaine étape). En attendant, vous pouvez rajouter votre projet à la liste au format .CSV du standard OpenKnowHow.
Pour cela allez sur le fichier de la liste des projets. Puis, cliquez sur le bouton éditer :
A la fin du fichier rajoutez votre projet, puis validez en demandant à faire un « fork » du fichier (au moment de la validation). Puis à l’étape suivante demandez une mise à jour du fichier aux administrateurs du « repository » afin que votre projet soit validé et rajouté dans la liste.
Il est important de rajouter votre projet parce que plus nous seront nombreux à adopter ce format de description des projets et plus les chances de devenir un standard reconnu qui permettra l’échange et l’interopérabilité des projets sera facilitée et importante.
Voilà c’est fini pour ce tutoriel. J’espère que vous serez nombreux à nous rejoindre et à adopter ce format de description de projets !
Happy making !
