Bel exemple de la Charrette : https://charrette.bike/pdf/documentation.pdf
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
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)
Dans mon univers d’imprimantes 3D, voici ce avec quoi nous travaillons, c’est parfait !
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).
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
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
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
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
Super, je note la date !