Groupe "Encourager le partage de documentation, retours d'expériences au sein du réseau français"

Adrien

Salut à tous,

Comme Dimitri, je me permet de lancer le sujet concernant le groupe :
"Encourager le partage de documentation, retours d'expériences au sein du réseau français".

Plusieurs outils de documentation ont été listés et présentés pendant le FabFest (Wikimedia, Makake, FabManager, Redmine, etc ... ), et un atelier à également été animé autour de cette thématique ( voir restitution : https://hackpad.com/Restitution-ateliers-fabfest-aprs-midi-3A4ivtRNDGg ).

Personnellement, j'ai testé plusieurs outils jusqu'à aujourd'hui :

Documentation via CMS Wordpress ( abandonné, trop de dev, pas optimisé)
Documentation par Redmine ( efficace avec le wiki et le forum intégré , mais dédié, j'ai l'impression, à une "élite" et pas pertinent pour la documentation de petits projets )

Je suis en train de tester Makake ( http://www.makake.co ) et j'avoue que je suis séduit par la structuration sous forme de briques et d'assemblages de briques. Je pense également tester "FabManager" présenter par Jean-Michel au FabFestival (http://fab-manager.com).

Je rajouterais également que ce qui ressort des discussions que j'ai eu avec les FabLabs autour de la documentation c'est que l'outils importe peu, tant qu'on sait où trouver les infos.

Dans ce cadre, je rejoins parfaitement ceux qui avaient dans l'idée d'agréer, d'une manière ou d'une autre, l'ensemble des documentations de la communauté et de les rendre disponibles sur une même page et avec un même outil de recherche.

.vince

Salut,

Quelques remarques sur le sujet :

Une optimisation existe pour wordpress : https://github.com/cloeduc/doculab
Je découvre Makake. L'idée est vraiment bonne mais c'est un choix de documentation centralisée et malheureusement fermée.
fab manager : J'ai l'impression que c'est une (très belle) vitrine.

Nous, on s'est lancé avec un media wiki (semantic) + forum phpbb.
Je reviens plus tard pour développer...

loic_fejoz

Bonjour,

J'ai aussi rajouté une partie bibliographie à la page du wiki
http://wiki.fablab.fr/Partage_de_documentation,_retours_d'expériences

Ce que je retiens des discussions, c'est qu'il faut partir sur un protocole/format d'échange d'abord.
Les deux que j'ai repérés sont (cf biblio) :

FabML
Thingtracker.net

Thingtracker a ma préférence car il y a déjà des implémentations et a comme vision d'être décentralisé.

J'ai jeté un œil sur fab-manager.com que nous allons tester à Nybi.cc. Il semble facile de lui rajouter thingtracker (sorte de fils RSS en JSON).

Du coup, ce serait intéressant de faire un moteur de recherche sur fablab.fr des trackers des FabLabs français.

a+
Loïc

.vince

@loic_fejoz a dit :

Ce que je retiens des discussions, c'est qu'il faut partir sur un protocole/format d'échange d'abord.

Oui ! Effectivement, je vois 2 axes. D'abord le format d'échange pour simplifier le partage des projets. Ensuite, l'optimisation des outils pour publier/réaliser des documentations.

Thingtracker a ma préférence car il y a déjà des implémentations et a comme vision d'être décentralisé.

Ca m'a l'air vraiment bien.

Du coup, ce serait intéressant de faire un moteur de recherche sur fablab.fr des trackers des FabLabs français.

Là, ça serait le top. Moteur de recherche et agrégateur (mais je n'ai fait que survoler le thingtracker).

loic_fejoz

Du coup, pour l’agrégateur, vous (les admin FabLab.fr) préférerez un truc développé en quoi ?

Backend : PHP + Postgresql ? NodeJS + ? Plugin Wordpress ?
Frontend : angularjs ? Plain HTML ?

Couby

+1 sur Thingtracker, le concept est plutôt bien :).

NodeJS + angular auraient ma préférence, cela reste un avis personnel .

Dans le domaine de l'encouragement au partage de documentation et au travail collaboratif sur des projets open, je trouve que Git gagnerait à être vulgarisé et popularisé au sein du réseau.
C'est loin d'être immédiat et facile, mais le "système" me semble plus qu'éprouvé dans le domaine du numérique pur.

loic_fejoz

Bonjour,

Pour les choix techniques coté serveur, j'attends d'autres avis et je lancerai des trucs après, même si personnellement je ne suis pas très au fait de NodeJS.

Comme tu le dis @Couby , GitHub est plutôt bien. J'y mets tous mes FabMoments aussi :
https://github.com/loic-fejoz/loic-fejoz-fabmoments/

L'avantage est que cela reste compatible ThingTracker aussi comme je le fais dans mon GitHub ci-dessus. Il faudrait par contre une petite interface pour faciliter les mises à jour, etc. Bref pas grand chose à développer mais faut juste le faire...
L'autre avantage est que de plus en plus de personnes doivent déjà avoir un compte GitHub pour collaborer sur un projet, et donc il y a un frein en moins comparé à un wiki par FabLab (cf discussions lors du FabLab Festival 2015).

L'inconvénient de GitHub est qu'il peut apparaitre comme complexe pour un néophyte comparé à une interface comme Fab-Manager.com.

Loïc

loic_fejoz

Re,

Après réflexion, il faudrait plutôt un truc genre ElasticSearch ou Solr pour le backend...
Un avis ?

Couby

En effet les avis ça peut être bien. En même temps ça se précipite pas, et puis c'est bien aussi que le ou les gens qui mettent la main à la patte prenne une orientation qui les inspire :).
Je ne pense pas que j'aurai de temps pour cela dans l'immédiat, alors si tu laisses Node de côté, ca va pas me froisser .
Entre ElesticSearch et Solr, aucune idée.

Côté Git j'aime bien GitHub aussi. Après ce n'est qu'un remote très populaire. Un autre qui gagne à être connu est Cubehero. C'est aussi un git remote qui offre une interface plus user friendly, à la fab-manager peut-être je ne sais pas je ne connais pas assez ce dernier pour comparer.
Ce qui est dommage côté Cubehero c'est que son auteur n'a pas ouvert le code de la plateforme, à ma connaissance. Ce qui n'est pas vraiment un soucis, on peut toujours pusher sur plusieurs remotes.

Mais en effet je te rejoins, Git ne s'apprend pas en 5 minutes. D'où l'intérêt de travailler aussi sur sa vulgarisation pour que ce soit plus sexy et que ça ne demande pas des semaines.

Adrien

Bonjour et désolé pour l'absence.

Comme a dit Olivier dans son mail, "tout le monde est pris par le quotidien", et ... j'ai fait comme tout le monde ^^

J'avoue que je n'arriverai pas à vous suivre sur les histories de backend, de serveur, etc ... car ce n'est pas mon domaine, et je préfère vous faire confiance sur ce sujet afin d'avancer plus rapidement.

Concernant les différents outils, déjà merci à Loic pour la mise à jour du wiki avec la bibliographie.

Ensuite, j'entend le faite que makake soit fermé et centralisé ( c'est d'ailleurs la première remarque que j'ai faites à ces créateurs ). Maintenant, je ne pense pas qu'il faille abandonner un outil parcequ'il est fermé. Je suis plutôt du partit d'expliquer aux gens les forces et les faiblesses de chaque outil afin qu'ils puissent choisir en connaissance de cause.

Je pense également que pratiquement tous les outils peuvent permettre de documenter correctement 80% des projets. Encore faut-il savoir ce que l'on entend par "correctement"

Ainsi, si vous êtes d'accord avec cette remarque, j'aimerais proposer quelques points pour avancer dans ce sens :

Faire une liste des outils de documentation connus avec points faibles/forts, niveau d'accessibilité, et autres critères qui nous sembleraient pertinents. Je pense par exemple à la liste des Lab qui l'utilise avec un lien vers leurs doc.
Etablir une liste de bonnes pratiques sur la documentation ainsi que les moyens pour y arriver ( en gros : documenter la documentation ^^). J'avais commencé à faire ce travail sur notre wiki. Il me reste beaucoup de points à voir ^^ http://wiki.lamachinerie.org/projects/documenter-son-projet/wiki
Mettre un lien pour chaque outil vers un exemple de documentation qui nous semble complet et pertinent afin d'établir un maitre étalon.

Autres idées qui me viennent par la tête. Je partage, on verra si c'est pertinent ou pas :

Diffuser des projets d'outils physiques qui peuvent aider à la documentation (éclairage open source pour les photos, différents tests de micros/caméras pour la documentation vidéo, ...)
Etablir un système de grade de la documentation. Du - au + documenté selon le niveau d'utilisation des bonnes pratiques par exemple ?
Ou encore, une notation par les utilisateurs ?
Du, coup récompenses dans les labos par du temps machine ?

Vous en pensez quoi ?

Bonne journée !

loic_fejoz

@Adrien Oui il faudrait faire tout cela aussi mais, pour moi, la priorité n'est pas là mais dans la mise en place d'un truc minimal de partage décentralisé qui permettra ensuite à chacun des outils d'évoluer tout en formant un réseau.

Dit autrement, pour moi, l'urgent et important sont les cas d'utilisation suivant :

Quand j'ai acheté du nouveau matériel, je cherche des projets les utilisant afin de trouver une idée de projet.
Quand j'ai une idée de projet, je cherche des projets similaires afin de connaitre les écueils à éviter.
Quand on me demande ce que l'on fait dans un FabLab, je peux facilement montrer un portfolio.

Bien évidement, il y en a d'autres mais je mets cela en priorité.
Mon deuxième point d'intérêt est effectivement les bonnes pratiques de documentation mais malheureusement cela ne réponds pas aux urgences ci-dessus.

Adrien

Bien d'accord avec les points que tu évoque, mais cela sous entend qu'une documentation existe déjà, qu'elle est utilisable et exploitable ... Donc quand tu dis que :

Quand j'ai acheté du nouveau matériel, je cherche des projets les utilisant afin de trouver une idée de projet.

Quand j'ai une idée de projet, je cherche des projets similaires afin de connaitre les écueils à éviter.

Quand on me demande ce que l'on fait dans un FabLab, je peux facilement montrer un portfolio.

Ça veux dire que :

Les documentations doivent donner le matériel utilisé et mettre l'information bien en évidence et a disposition
Des mot-clefs ont été attribués par projet et documentation afin de simplifier les recherches.
Des photos corrects du projet ont donc été prises afin de le documenter proprement.

Pour moi ce que tu énonce fait donc références directement à des bonnes pratiques de documentation qui doivent être respectée avant de continuer à avancer ?

loic_fejoz

La poule et l’œuf...

Si l'on veut savoir quoi écrire comme doc, il faut bien savoir ce que l'on veut en faire.
Donc si ce sont bien ces usages qui nous intéresse dans la doc, alors ça veut dire que...
Et donc cela veut dire qu'il faut des outils, templates, recommandations, qui disent que...

Mais c'est bien l'usage de la documentation qui tire les besoins, non ?

Adrien

Oui effectivement.

Donc pour avancer selon toi, il faudrait lister ce que nous aimerions avoir dans une doc et regarder quoi mettre en face pour y arriver (outils, bonnes pratiques, tutos, etc ... ) ?

loic_fejoz

Pour moi, il faut savoir pourquoi on veut une doc, ce que l'on veut en faire, ensuite nous verrons comment arriver à cet état où la doc est utilisable.

On peut vouloir une doc pour plein de raisons. D'ailleurs dans le domaine pro, nous avons des choses bien identifiées :

guide utilisateur,
guide de montage,
cahier de laboratoire (pour lister ce que l'on fait, les erreurs, etc),
le cahier de spécification,
concept opérationnel,
etc.

Bref tout un monde de subtilité mais surtout d’objectifs différents qui ont donc des réponses différentes mais que nous, FabLab, recoupons sous le terme de "doc"...

Adrien

Ok donc commençons par regarder pourquoi souhaiterions nous avoir une doc alors. On y verra plus clair sur la suite de la démarche ?

Pour travailler sur ce point, on liste dans le forum, dans un pad ou dans une carte heuristique ?

loic_fejoz

On peut en discuter ici d'abord et synthétiser dans le wiki...
http://wiki.fablab.fr/Partage_de_documentation,_retours_d'expériences

Adrien

Ok je me lance.

J'ai scindé ma réflexion en trois selon que j'était responsable du lab, utilisateur ou maker car je pense que les attentes ne sont pas les même.

Pour moi et le lab, en tant que FabManager, j'ai besoins d'une doc pour :

Lister les projets réalisés dans le lab
Pouvoir greffer des makers au projet
Connaitre les besoins et usages sur les machines afin d'améliorer leur utilisation

Coté utilisateur, quand je vois un projet, j'ai besoins d'une doc pour :

Comprendre comment le projet fonctionne
Permettre de le recréer
Comprendre ce qui a fonctionné ou pas
Connaitre les projets similaires

Coté makers, j'ai besoins d'une doc pour :

Structurer mes notes de projets
Stocker mes idées, liens, inspirations
Stocker et structure mes fichiers de projet par version
Discuter avec les gens du projet ( forum, avis, commentaires )

loic_fejoz

A quelques nuances près, je suis d'accord avec tout cela...
Maintenant, il faut prioriser. C'est ce qui a donné

@loic_fejoz a dit :

[...]
Dit autrement, pour moi, l'urgent et important sont les cas d'utilisation suivant :

Quand j'ai acheté du nouveau matériel, je cherche des projets les utilisant afin de trouver une idée de projet.

Quand j'ai une idée de projet, je cherche des projets similaires afin de connaitre les écueils à éviter.

Quand on me demande ce que l'on fait dans un FabLab, je peux facilement montrer un portfolio.
[...]

Adrien

@loic_fejoz a dit :

A quelques nuances près, je suis d'accord avec tout cela...
Maintenant, il faut prioriser. C'est ce qui a donné
[...]

Ok, je comprend ton cheminement maintenant. A moi de prioriser maintenant

1 - Portfolio : Ça on est d'accord, on doit avoir une vitrine de ce qui est fait pour pouvoir la présenter
2 - Les mots clef : Permettre de trouver facilement par recherche de mots clefs dans la description du projet, soit des projets similaires, soit des projets utilisant le même matériel, soit des projets utilisant la même machine/technique
3 - Stocker des fichiers : Permettre au makers de déposer un fichier afin de pouvoir le partager et permettre une amélioration