basé sur http://carrefour-numerique.cite-sciences.fr/fablab/wiki/doku.php?id=aide:documenter

Comment je documente ? Et Pourquoi ?

Le wiki de PLANU.be est un site contributif et l'accès est gratuit, mais en échange :

Vous vous engagez à participer aux autres projets en cours au moment où vous vous trouvez sur place. Vous faites bénéficier les autres de vos savoirs, et les autres vous font bénéficier de leurs savoirs.
Vous vous engagez à documenter ce que vous réalisez : à savoir, écrire la “recette de cuisine” de votre objet pour que d’autres puissent le refaire. Notez que cela ne vous empêche pas d'en faire une exploitation commerciale, en choisissant une licence adaptée.
Vous vous engagez à partager cette documentation, en la publiant sur notre wiki. Ce partage peut se faire sous une licence qui restreint l’exploitation commerciale de votre projet, mais qui en autorise par défaut la reproduction à titre personnel, et les modifications, comme par exemple une licence Creative Commons.

Documenter son projet, c'est réaliser une page dédiée à votre réalisation dans la rubrique index, avec la description des différentes étapes du projet, les difficulté rencontrées etc.… Mais c'est aussi :

Documenter l'utilisation des machines dans la rubrique dédiée (procédure, astuces, réglages, …)
Documenter les logiciels utilisés (tutoriaux, astuces, plugins utiles, …)
Indiquer dans la rubrique Les ressources/Fournisseurs de matériaux où vous vous êtes procurés vos matériaux et les potentiels bons plans ou remarques que vous auriez à partager.
Ajouter des liens vers les ressources qui vous ont été utiles durant votre projet dans la rubrique index
Rédiger de petits articles sur tel ou tel sujet que vous auriez appris ou approfondi lors votre réalisation, et qui pourraient être utiles pour d'autre projets (comme par exemple l'article sur les engranges_denture_droite)
…

Votre documentation permettra ainsi à d'autres usager·e·s de Fab Labs de refabriquer, d’améliorer ou d'adapter votre réalisation, mais aussi de partager les connaissances que vous aurez acquises lors de votre projet avec les autres utilisateur·trice·s.

N'hésitez pas non plus à corriger ou améliorer le contenu déjà présent dans ce wiki.

Documenter mon projet, mais comment ?

Pour commencer, créez une page pour votre projet dans la section projets. Vous pouvez utiliser le formulaire présent en haut de la rubrique pour créer votre page.

Lorsque vous créez une page dans la rubrique projets un squelette vous est proposé pour vous aider dans la rédaction. Les parties indiquées entre <html><!–</html> et <html>–></html> sont des commentaires, non affichés sur la page, ils vous guideront dans la rédaction et vous pouvez les supprimer.

Voici une présentation des différentes parties que nous vous proposons d’intégrer dans votre documentation. Ces quelques lignes directrices sont bien sur indicatives, et vous pouvez adapter la structure de votre page en fonction de vos besoins. Les éléments proposés nous semblent être une bonne base pour documenter un projet. Vous pouvez commencer la documentation de votre projet même si celui-ci n'est pas encore terminé.

Nom du projet

Indiquez le nom/titre de votre projet en haut de la page, en utilisant un titre de niveau 1 (H1), c'est à dire entouré de <html>======</html>. Par exemple

===== Goodies Open Bidouille Camp =====

Lorsque vous créez votre page, le titre sera pré-rempli, mais vous pouvez le modifier s'il ne vous convient pas.

Fiche projet

Dans le squelette fourni lors de la création de votre page vous trouverez une fiche projet à compléter :

{{{project
picture:
machines: 
materiaux:
logiciels:
fichiers:
liens:
tags:
usager:
licence:
}}}

Cette fiche contient différents champs qui permettront d'afficher une petit encart de résumé en haut à droite de votre page projet, mais aussi de pouvoir facilement retrouver la réalisation à partir de son contenu. Elle contient différentes informations :

picture : Photo du rendu final de votre projet, vous pouvez l'ajouter en utilisant le bouton Ajout d'image. Exemple :
```
picture:{{:gallerie:boite_crayons_cutters_ciseaux:dsc_3481.jpg?200|}}
```
machines : Liste des machines utilisées lors de la réalisation, séparées par des espaces. Il faut ici, si possible, indiquer l'identifiant de la page de la machine utilisé dans la rubrique machines du wiki. Exemple :
```
machines: impression_3d:orca decoupe_laser vinyle:decoupeuse
```
materiaux : Liste des matériaux utilisés pour votre projet, séparés par des espaces. Ici encore, lorsque cela est possible, utilisez le nom de la page matériaux tel quelle existe dans la rubrique idoine Vous pouvez, bien sur, créer une page si vous utilisez un matériau non encore référencé. Exemple :
```
matériaux: medium pmma abs pla cahoutchouc
```
logiciels : Liste des logiciels utilisés lors de du projet. séparés par des espaces. Ici aussi, lorsque c'est possible, utilisez le nom de la page concernant ce logiciel dans la rubrique logiciels. Exemple :
```
logiciels: inkscape freecad slic3r
```
fichiers : Fichiers sources et fichiers de fabrication du projet(modèles 3d, fichiers svg, codes sources, …) , séparés par des espaces. Vous pouvez ici utiliser le bouton Ajouter des images ou d'autres fichiers pour faire un lien vers des fichiers hébergés sur le wiki, ou bien utiliser des urls vers de fichiers hébergés sur d'autres serveurs. Exemple :
```
fichiers: {{:projets:obc_goodies:mains_obc.svg|}} http://www.thingiverse.com/download:122201
```
liens : Liste de liens vers des ressources intéressantes ou vers d'autre projets qui vous ont inspirés. Vous pouvez utiliser tout type de lien supporté par la syntaxe dokuwiki (lien interne, lien externe ou interwiki). Exemple :
```
liens : [[projets:flocons_laser|]] [[wpfr>Flocon]] http://www.instructables.com/id/Paper-chain-snowflakes/
```
tags : Liste de mots clefs catégorisants votre réalisation, séparés par des espaces. Exemple :
```
tags: boite bois steampunk bijoux
```
usager : Login du ou des usager·e·s ayant participé·e·s à la réalisation, séparés par des espaces. Exemple :
```
usager:bully isa
```
licence : Licence(s) sous laquelle vous souhaitez partager votre projet. Par exemple cc-by-sa, cc-by, cc-by-nc, … pour une Licence Creative common, ou bien encore agpl, gpl, art-libre, etc.… (Pour vous aider dans le choix de votre licence vous pouvez consulter le rubrique licences du wiki.)
```
 licence : cc-by
```

Introduction

Juste après la fiche projet, et avant le premier sous-titre, vous pouvez indiquer quelques mots/phrases d'introduction présentant le projet, expliquant d’où est venue l'idée etc.… C'est cette petite introduction qui sera visible dans la liste des projets.

Conception

Vous pouvez dans la rubrique conception détailler la phase de réflexion sur le projet. Comment vous avez conçu votre réalisation, quelles étaient les contraintes à prendre en compte etc.…

Réalisation

Dans la rubrique réalisation vous pouvez expliquer étape par étape comment vous avez concrétisé et fabriqué votre projet. N’hésitez pas à illustrer les différentes étapes par des schémas et/ou photos. Indiquez comment vous avez utilisé les machines et outils, quels réglages etc.…

Difficultés rencontrées

Rien de mieux que de se tromper pour apprendre de ses erreurs. Indiquez les difficultés et problèmes rencontrés durant la conception et le réalisations de votre projet, et comment vous avez résolu ces problèmes, ou ce que vous changeriez si vous aviez à le refaire.

Suites du projet

Vous envisagez une suite à votre projet, vous voyez des améliorations ou compléments qui pourraient y être apportés ? N’hésitez pas à les présenter, qui sait peut être qu'un·e autre utilisateur·trice du Fab Lab pourra s'en emparer ou vous aider.

Remarque sur la syntaxe dokuwiki : Essayez d'utiliser les niveau de titres (boutons H dans la barre d'outils) en commençant avec un titre de niveau 1 (H1) comme titre de page. Les fonctions gras, italique, souligné sont à éviter pour les titres et sous-titres.

N'utilisez que des contenus dont la diffusion est autorisée (généralement sous licence libre).

N'oubliez pas d'indiquer vos sources (en note de bas de page, ou bien dans la rubrique liens de la fiche projets, par exemple).

Si aucune fiche de wiki ne correspond au logiciel ou à la machine que vous avez utilisé, c'est l'occasion d'en créer une. Vous pouvez aussi renvoyer vers un autre site.

Pour connaître la syntaxe particulière de DokuWiki (le logiciel utilisé pour ce site), consultez la syntaxe de mise en page.

Pour télécharger un fichier, utilisez le gestionnaire de médias (ouvrez-le dans un nouvel onglet). N’hésitez pas à créer des namespace pour ranger vos images et fichiers plutôt que de les laisser à la racine du wiki ou de la rubrique projets. Pour créer un namespace il convient de préfixer le nom du fichier avec le chemin que l'on souhaite créé après avoir sélectionné ses fichiers. Le nom du fichier s'affiche dans un champ. Il suffit alors de saisir le chemin souhaité, par exemple mon-espace:mon_projet:image.jpg. En cliquant sur “Télécharger”, les images s'enregistreront dans le namespace souhaité. (⇒ Plus de détails dans la rubrique upload_fichiers)