(l'art de la) Documentation pour produire en mode DIY

Bel exemple de la Charrette : https://charrette.bike/pdf/documentation.pdf

1 « J'aime »

chez nous il y a eu des arbitrages sur la doc. Pour qu’elle soit le plus évolutive et participative possible des outils type git / readthedocs sont testés. Mais par conséquent c’est pas aussi beau que Veloma (charrette) qui a missionné une graphiste. Dilemme :sweat_smile:
On pourrait aussi décider de sortie une belle doc de temps en temps, qui serait une photographie de la doc à un moment précis, joyeusement mise en page (ce que fait par exemple l’association tripalium avec ses guides de construction d’éoliennes)

1 « J'aime »

Dans mon univers d’imprimantes 3D, voici ce avec quoi nous travaillons, c’est parfait !

1 « J'aime »

Ca n’est pas très sexy, c’est un prototype issu d’un projet Européen, mais ça a le mérite d’exister.

Se poser la question de la documentation, c’est aussi se poser la question de l’ouverture et donc du niveau d’information que l’on délivre et pourquoi. Souhaite t on permettre la duplication, la réutilisation, l’enrichissement de la conception ?
Le template ne donne pas la réponse à ces questions, mais juste explore TOUTES les informations pertinentes à fournir dans un idéal d’open-source total (définition de l’OSHWA : study, make, replicate, sell).

2 « J'aime »

En effet, sujet majeur dont nous devrions avoir un petit atelier du jeudi matin dédié ! qu’en pensez vous @psl3d @constance-rfflabs @Vehicule_Techno @pierre_vspt

1 « J'aime »

oui bonne idée. Je rajoute @andreaslivet qui a converti la doc Vhélio au format git

Oui le sujet de la documentation est pas évident. Sur le vhélio on est parti sur git + le format Myst (une sorte de Markdown augmenté qui est utilisé notamment par Readthedoc).
Personnellement, je trouve ça super, mais je me rends compte que ça ajoute un niveau de complexité non négligeable pour les néophytes.
L’idée était de pouvoir permettre à tout le monde de contribuer à la doc en toute autonomie (via le mécanisme de « Pull Request »), en pratique, c’est finalement les personnes qui maîtrise l’outil technique qui devait centraliser les modifs et les faire elles-mêmes.
De plus, le rendu PDF a été difficile à bien calibrer, ces documentations étant plutôt faites pour du rendu HTML.
Nous sommes arrivé à quelque chose de plutôt joli (pas autant que Veloma bien sûr) et ça pourrait être intéressant de vous partager notre expérience.
Je pense qu’il sera important de bien documenter aussi la procédure qui permet de contribuer à la doc, pour l’instant c’est encore trop compliqué.
Dispo un jeudi matin si vous voulez (faudra que je prévienne le boulot).
Bonne journée,
Andréas

3 « J'aime »

Merci pour ces retours très riches ! Ce sujet est le coeur du réacteur si on veut avoir 5% de personne capable de documenter dans chaque communauté/projet
Cc @jaime

1 « J'aime »

Viens d’organiser l’Atelier du 20 avril sur ce sujet ! Faites circuler l’info
https://wiki.lafabriquedesmobilites.fr/wiki/Atelier_XD_58_documentation
en espérant avoir les équipes de Vhélio, Charette cc @veloma @Vehicule_Techno

1 « J'aime »

Super, je note la date !

Ce guide vient d’être rédigé pour la documentation de vos projets Guide de documentation pour l'extrême Défi — Communauté de la Fabrique des Mobilités

le CERN vient de mettre à jour sa plateforme pour héberger des projets open source Hardware : CERN’s new Open Source Program Office | CERN

pour Vhélio et Mosquito ? cc @marcl73 @Vehicule_Techno

1 « J'aime »