Comment documenter ?
C'est quoi une documentation ?
Tout projet réalisé partiellement ou intégralement au fablab doit obligatoirement être documenté sur ce wiki ! C’est un peu votre monnaie d’échange pour avoir accès aux outils du Fablab. C’est aussi un prérequis de la Charte des Fablabs.
N'hésitez pas à demander l'aide d'un.e médiateur.ice pour réaliser votre documentation !
La documentation est la trace écrite de toutes les étapes vous ayant permis de réaliser votre projet. Elle vous permet de partager vos erreurs, vos découvertes, vos astuces, vos fichiers... et sera très précieuse pour toute personne cherchant à se former, à s'inspirer, à élaborer un projet similaire.
Elle vous sera également très utile si vous souhaitez revenir plus tard sur ce projet ou sur une des techniques que vous avez utilisée, ainsi que pour communiquer sur ce projet.
Voici les éléments qui doivent obligatoirement figurer sur votre documentation
- Nom du projet
- Coordonnées (nom, prénom, adresse mail, cursus / labo)
- Introduction (date de début, date de fin estimée, objectifs, contexte)
- Matériaux / Outils / Machines (le plus détaillé possible)
- Construction (fichiers, photos, code, texte, paramètres d’usinage etc.)
- Journal de bord (étapes datées du projet, facultatif pour les petits projets)
⭐ Une documentation correcte doit vous permettre de refaire le projet de A à Z plusieurs mois plus tard.
⭐⭐ Une bonne documentation doit permettre à n’importe quel usager de refaire le projet de A à Z.
⭐⭐⭐ Une excellente documentation fait tout ça mais permet aussi de comprendre tout le processus itératif
Où et comment documenter sur ce wiki ?
Pour garder les choses à peu près organisées, on fait la distinction entre deux types de projets :
1. Les petits projets
Ce sont des projets de petite ambition technique, nécessitant un recours ponctuel aux ressources du Fablab, typiquement une seule venue au Fablab, avec peu d'étapes de développement.
Ils doivent malgré tout comporter toutes les informations minimales mentionnées plus haut.
Merci de respecter le processus suivant :
1. Vous rendre dans la section Petits projets, (elle-même dans l'étagère 2-Projets)
2. Créer une nouvelle page en cliquant sur l'action "Nouvelle page" dans le menu latéral. Cela ouvre une nouvelle page vierge dans un éditeur de texte.
3. Toujours dans l'éditeur, sélectionner un modèle de page en cliquant sur la dernière icône du menu latéral à droite
4. Cela ouvre un volet latéral. Sélectionner le modèle intitulé "Modèle de documentation générique" en cliquant sur l'encadré
5. Cela fait apparaître directement le modèle dans l'éditeur de texte. Tout est prêt pour que vous commenciez à documenter, il ne reste plus qu'à modifier le contenu des différentes sections.
📸 Ne lésinez pas sur les photos et captures d’écran
On insère une image en cliquant sur l'icône d'image dans le menu du haut de l'éditeur.
6. Ajoutez un / des tags à votre page.
Entrez les premières lettres du tag puis sélectionnez-le. Vous pouvez ajoutez plusieurs tags. Au besoin voici comment afficher la liste des tags existants. Une fois que c'est fait, vous pouvez refermer le volet en cliquant sur la flèche rouge.
Attention de bien sélectionner un mot-clé existant et de ne jamais en créer un nouveau pour éviter le chaos général !
Si le mot-clé que vous cherchez n'existe pas et que vous pensez qu'il mériterait d'apparaître sur ce wiki, rapprochez-vous d'un.e médiateur.ice.
7. N'oubliez pas d'ajouter vos fichiers sources !! Pour cela cliquez sur l'icône de trombone dans la menu latéral de droite. Le volet s'ouvre. Cliquez sur "Uploader un fichier" et glissez-le dans la boîte grise.
2. Les projets classiques
Projets nécessitant plusieurs venues au Fablab / un développement plus important, les projets classiques ne se rangent pas au même endroit ! Par ailleurs, au lieu d'être rédigés en une seule page, ils contiennent plusieurs pages, qui peuvent même être rangées en chapitres.
1ère possibilité : utiliser un modèle de livre
Merci de suivre le processus suivant :
1. Ouvrir le livre Modèle de Projet en cliquant sur ce lien (ou en le cherchant dans l'étagère 2-Projets)
2. Dupliquez-le en cliquant sur "Copier" dans le menu latéral
3. Attention à bien renommer votre copie dès cette étape sinon vous risquez de confondre le modèle et la copie
4. Déplacez votre copie dans l'étagère "2 - Projets"
Pour cela :
- se rendre dans l'étagère 2 - Projets
- cliquer sur "Editer" dans le menu latéral
- Retrouvez votre projet dans la liste de droite et glissez-le dans la liste de gauche pour l'ajouter à l'étagère des Projets
- Cliquez sur "Enregistrer"
5. L'étagère "2-Projets" s'ouvre : cliquez sur votre projet nouvellement créé et déplacé, et c'est parti pour rédiger votre documentation 🔥🔥🔥
6. Cliquez sur "Editer" dans le menu latéral et changez la couverture de votre livre pour une image liée à votre projet.
7. Profitez-en pour ajouter des mots-clés. Attention, il ne faut pas créer de nouveaux mots-clés pour ne pas engendrer le chaos : commencez à taper le nom d'un tag puis sélectionnez-le lorsqu'il apparaît. Au besoin voici comment afficher la liste des tags existants.
8. Vous pouvez désormais cliquer sur chaque page du template. Pour la modifier et la compléter, cliquez sur la page en question puis cliquez sur "Editer".
📸 Ne lésinez pas sur les photos et captures d’écran !
9. N'oubliez pas d'ajouter vos fichiers sources !! Pour cela cliquez sur l'icône de trombone dans le volet de droite lorsque vous êtes dans l'édition d'une page. Un volet apparaît. Cliquez sur "Uploader un fichier" et glissez-le dans la boîte grise.. Ils seront ainsi joints à la page (sans apparaître dans le corps du contenu).
Vous pouvez réorganiser l'ordre des pages en cliquant sur "Trier" dans le menu latéral (lorsque vous êtes au niveau du livre et pas à l'intérieur d'un chapitre ou d'une page).
2ème possibilité : créer un livre vierge
1. Se rendre dans l'étagère "2 - Projets".
2. Créer un nouveau livre en cliquant sur "Nouveau Livre" dans le menu latéral (icône de +)
3. Nommez-le et choisissez une image de couverture.
4. Ajoutez des mots-clés puis cliquez sur "Enregistrer le livre". Attention, il ne faut pas créer de nouveau mots-clés pour ne pas engendrer le chaos : commencez à taper le nom d'un tag puis sélectionnez-le lorsqu'il apparaît. Au besoin voici comment afficher la liste des tags existants.
5. Créez des pages et des chapitres
6. Rédigez votre documentation en allant dans une page puis en cliquant sur "Editer"
📸 Ne lésinez pas sur les photos et captures d’écran !
9. N'oubliez pas d'ajouter vos fichiers sources !! Pour cela cliquez sur l'icône de trombone dans le volet de droite lorsque vous êtes dans l'édition d'une page. Un volet apparaît. Cliquez sur "Uploader un fichier" et glissez-le dans la boîte grise.. Ils seront ainsi joints à la page (sans apparaître dans le corps du contenu).
Vous pouvez réorganiser l'ordre des pages en cliquant sur "Trier" dans le menu latéral (lorsque vous êtes au niveau du livre et pas à l'intérieur d'un chapitre ou d'une page).