Pourquoi et comment documenter

Le Guide de l'Open Source de Github : https://opensource.guide/fr/

Les différentes contributions

  • Sur le wiki :
  • Hors du wiki :
    • parler d'apprentiLAB autour de vous
    • répondre à une question sur le forum ou le chat
    • mettre à disposition ses compétences sur un projet existant
    • faire des tests matériaux sur une machine
    • faire un objet de démonstration pour illustrer ce qu'il est possible de réaliser
    • proposer un évènement pour faire vivre la communauté : rencontres, présentations des projets, invitations de partenaires
    • etc.

L'équipe d'apprentiLAB a travaillé dur pour vous fournir un wiki accessible, lisible et flexible.

Nous utilisons pour cela une application libre et Open Source, Dokuwiki. Qu'est-ce que Dokuwiki ?

Nous l'avons configurée et structurée à notre sauce, notamment en créant des templates de pages afin de vous proposer une structure ergonomique, qui nous pousse tous à bien documenter, et qui facilite la lecture par une personne extérieure.


Si vous avez fait un tour dans le wiki, vous remarquerez qu'il y a différentes sections, et différents types de pages. Un utilisateur non-enregistré peut seulement voir les pages, un utilisateur connecté peut éditer certaines pages (par exemple le Bac à sable, les pages Réalisations et Tutoriels).
Enfin, certaines autres pages qui servent de documentation “fixe” et ne sont pas éditables (par exemple la page sur laquelle on se trouve, la page d'accueil, les pages machines…).

Si vous êtes perdus, cliquez sur le Plan du site dans la boîte à outils en haut à droite !

Apprendre à utiliser Dokuwiki

→ Pour commencer vous pouvez consulter le Manuel de Dokuwiki

Pour s'entraîner et tester la syntaxe dans une page qui ne craint rien, vous pouvez ouvrir Bac à sable, et cliquer sur “Modifier cette page”.

Vous éditer la page en syntaxe dokuwiki, comme vous pouvez le remarquer ça n'a pas la même tête que le rendu final de la page. Pour comprendre cette syntaxe, consulter la page d'aide sur la syntaxe Dokuwiki : Syntaxe de mise en page. Vous pouvez cliquer à tout moment sur le bouton “Aperçu” pour voir en même temps votre texte en syntaxe dokuwiki, et dessous l'aperçu du rendu.

Pour aller plus loin dans les outils :

Contribuer à une page existante

Vous pouvez corriger/enrichir une page existante en cliquant sur “Modifier cette page”, par exemple en ajoutant une idée à la La boîte à idées. Si vous ne voyez pas ce bouton en haut d'une page, c'est que vous n'avez pas les droits d'édition dessus (par exemple dans les pages Machines). On les a bloquées pour éviter les fausses manips sur des pages importantes, mais si vous souhaitez les modifier, vous pouvez poster dans le forum pour suggérer des modification, ou nous contacter directement par mail ou par le chat.

Créer une nouvelle page

Vous pouvez créer une nouvelle page Réalisation si vous souhaitez partager la documentation de votre projet et expliquer comment le reproduire, l'utiliser, le développer, etc.

Vous pouvez également contribuer à la base de connaissances d'apprentiLAB en créant des Tutoriels.

Ces pages s'appuient sur des modèles de pages, ou templates, dont la structure et les instructions sont censées vous guider dans la rédaction. Vous y trouverez directement des conseils et des exemples.

  • 👥 Éviter les redondances : pas besoin de réexpliquer en long et en large quelque chose qui a déjà été très bien documenté ailleurs. On peut mettre un lien vers ces autres pages, avec une courte description de ce qu'elles contiennent.
  • 👩‍🏫 Se mettre à la place de la personne qui vous lit : est-ce que ma page comporte assez d'infos pour que n'importe qui s'y retrouve ? L'idée c'est d'éviter les pages qui restent indéfiniment à l'état de brouillon, avec juste un lien et un fichier…
  • Orthographe : on né pa la poure vou jujé sure la forme 😉

Voir par ici : https://apprentilab.cnam.fr/ressources-numeriques

On peut accéder aux ressources via le Portail, ou via le panneau du haut (si vous êtes connecté).

  • contribuer/comment-documenter.txt
  • Dernière modification: 2021/10/29 11:54
  • de apprentilab