owned this note
owned this note
Published
Linked with GitHub
# Guide: Qu'est-ce qu'une bonne documentation ?
Lorsque vous souhaitez réaliser un projet de fabrication numérique, il peut-être important de trouver en amont des ressources pour mieux s'orienter, des conseils, voire des projets similaires sur lesquels s'appuyer.
Le but de ce guide est double : vous donnez des pistes et des critères afin de mieux sélectionner la documentation sur internet, ainsi que vous munir pour mieux documenter votre projet.
## Les plateformes de projets
Plusieurs types de plateformes documentaires existent pour les projets de fabrication numérique :
### Les dépôts
Les dépôts sont des plateformes qui ne donnent que très peu de critères pour la documentation et servent avant tout à mettre à disposition des fichiers, que cela soit des fichiers d'impression 3D, vectoriels...
Parmi les plus consultés nous trouvons :
**Thingiverse :** https://www.thingiverse.com/
**3axis :** https://3axis.co/
**My Mini Factory :** https://www.myminifactory.com/
Le fonctionnement de ces sites se repose beaucoup sur le retour utilisateur de la communauté sur les projets, afin de pouvoir, pour les contributeur·ices, actualiser et améliorer le projet.
### Les wikis
Ici nous entendons par "wiki" des plateformes qui vont servir de "manuel d'utilisation" aux utilisateur·ices. Ce type de plateforme est fréquemment utilisé pour documenter les langages de programmation, sans définir d'usage particulier au code. Ces base de données peuvent reposer sur la contribution mais sont contrôlées et modérées.
**Raspberry Pi documentation :** https://www.raspberrypi.org/documentation/
**Arduino Reference :** https://www.arduino.cc/reference/en/
### Les plateformes de tutoriels
Plus proche de la communauté makers, il y a les plateformes de tutoriels, où vous pouvez trouver des projets ayant été réalisés ou en train d'être réalisés. Basés exclusivement sur la contribution de la communauté, ces sites offrent des structures de documentation plus complètes (difficulté, budget, matériaux) et plus accessibles au grand public. Cependant, la modération de ces sites est faible et les niveau de précision des tutoriels peuvent varier.
Nous pouvons par exemple citer :
**Instructables :** https://www.instructables.com/
**Wikifab :** https://wikifab.org/wiki/Accueil
## Le tutoriel
La forme la plus courante de documentation des projets makers est le tutoriel. Il s'agit d'un document pédagogique conduisant, étape par étape, à la réalisation d'un projet de fabrication. Un tutoriel est applicatif et donc situé. Nous entendons par là que par défaut, changer un paramètre du tutoriel (une étape, un matériau, une technologie) modifiera le projet de manière plus ou moins conséquente.
Lors de la recherche d'un tutoriel, certains critères vont vous aider à trier la documentation.
### La difficulté
Avant tout, situer une difficulté au sein d'un tutotiel est une pratique qui peut être discutée. Il est impossible de prévoir qui verra la documentation du projet, de même que jauger une difficulté nécessite un retour réflexif sur votre propre niveau. Elle se jauge avant tout sur des compétences ainsi que des savoir-faire qui sont propre à chacun·e et il est donc plus avisé de donner, en introduction, les savoir-faire auxquels font appel le tutoriel.
### Les matériaux
La liste des matériaux est le premier élément que vous devez regarder. L'accessibilité des matériaux est une question revenant régulièrement. Aussi, un lien vers les matériaux est toujours souhaitable et permet de se rendre compte rapidement du budget nécessaire à votre projet si celui-ci n'est pas indiqué. Par ailleurs, soyez viligant·e aux projets basés sur la récupération de matériaux, car si elle s'inscrit dans une démarche ethique, elle oppose une difficulté supplémentaire pour trouver les éléments.
En ce qui concerne les composants électroniques, veillez tout d'abord à ce que la référence des composants soit toujours précisée (l'idéal est également d'avoir un lien vers l'achat du composant). La disponibilité des composants peut également varier.
### L'électronique
Les circuits électroniques et schémas de branchements indiqués dans la documentation doivent être compréhensible si vous n'avez jamais fait d'électronique. Un moyen rapide d'identifier si la documentation s'adresse à un large public est de regarder la manière dont est documentée la partie électronique du projet.
![](https://i.imgur.com/GWVre94.png)
Les schémas en électronique sont standardisés et demandent de comprendre certains codes spécifiques pour pouvoir être lus. Dans une optique d'accessibilité, une pratique à adopter est de schématiser de manière plus concrète le branchement comme ceci :
![](https://i.imgur.com/61fY5W4.png)
Pour cela, vous pouvez utiliser 2 outils :
**Tinkercad Circuits, simulateur de prototypage électronique en ligne :** https://www.tinkercad.com/circuits
**Fritzing, application open-source de schémas électroniques (payante - 8€):**
https://fritzing.org/
### Les outils
Bien souvent, l'utilisation d'outils est sous-entendue : la soudure de composants implique de disposer d'un fer à souder. L'idéal est que ces outils soient indiqués dans une partie dédiée (c'est le cas sur WIkifab). De cette manière vous n'aurez pas à chercher dans le tutoriel si vous avez besoin d'un outil ou d'une machine spécifique.
### Images et fichiers
En tutoriel, les images et photos sont complémentaires. Les schémas aident à se représenter de manière abstraite les assemblage, circuits, etc... alors que les photographies rendent intelligibles l'action à effectuer.
Certains tutoriels donnent également accès aux fichiers de projets, et dans ce cas, vous n'aurez qu'à modifier le fichier en fonction de vos besoins. Si vous documentez un projet, essayez de mettre à disposition des fichiers modifiables facilement, par exemple sous des formats universels (.stl ou .obj pour la 3D, .stl pour les dessins vectoriels)
### Les licences
Les projets trouvés sur internet ont parfois une licence d'attribution destinées à protéger la réalisation du plagiat ou d'une exploitation non désirée par l'auteur·e. Cette pratique, venant au départ du logiciel libre, s'est étendue à la communauté makers.