C'est un brouillon en cours de rédaction.
L'objectif est de faire de cette page le point d'entrée pour accéder à toute information du lab.
Ce chapitre contient la métadoc, c'est à dire la documentation de la documentation.
Il informe sur l'objectif attendu de la documentation, et les règles qu'on souhaite respecter pour avoir une doc la plus efficace possible.
Depuis la v1 et ses 150m^2, le lab a grandi organiquement, parfois de manière chaotique.
Au moment du commencement de cette doc (2021), le constat est qu'il n'y a presque aucune de documentation concernant tous les outils, toutes les procédures, et plus généralement tous les aspects du lab.
Lorsque de la documentation existe, il n'y a pas de moyen de savoir qu'elle existe. Il n'y a pas de méthode systématique pour la recenser et l'enrichir.
Donc forcément, lorsqu'un membre arrive pour la première fois, il est complètement perdu. Impossible de trouver des outils, de savoir comment s'en servir, ni même de savoir qu'ils existent, sans demander toujours aux même têtes connues qui sont toujours là.
Et c'est même valable pour les membres de longue date, dès qu'on sort de sa zone, et des outils qu'on utilise habituellement.
On ne sait pas ce qu'on ignore. Si par exemple je souhaite découper une plaque en métal, mais que j'ignore ce qu'est une torche à plasma, je vais avoir tendance à utiliser une dremel alors que la torche pourrait marcher beaucoup mieux, être moins dangereuse, etc.
(Ce problème appelé "discoverability" en anglais n'a pas vraiment de traduction admise)
Il faut donc un point d'entrée unique à partie de laquelle je puisse découvrir tout l'univers proposé par le lab.
Solutions :
Lorsque que l'on va par exemple faire un tour sur le wiki historique du lab, la majorité des pages sont obsolètes, parfois avec une alerte en haut de la page, parfois même sans.
La difficulté dans l'accès à l'information est de savoir si une information est toujours valable, ou si pour une raison quelconque ce qu'on lit est obsolète.
Un tas de raison peuvent provoquer l'obsolescence:
Solutions :
TODO
Pas de prescription sur la forme, faut pas brider. a mettre sur les conseils de redaction.
parler d'équilibre entre formalisme efficace et spontanéité légèreté.
Doc technique
Rétrolien pour déterminer si la doc est accessible.
Parler de l'état de la doc, début en IT, suite tout.
Parler des qrcodes
Dans cette section on retrouve des règles un peu plus formelles pour faciliter le maintient en état de la doc, un peu comme une checklist qu'on valider rapidement sans trop réfléchir.
"Si c'est pas trouvable, ça n'exite pas."
Toute documentation concernant le lab doit être atteignable par des simples clics depuis la page d'accueil https://doc.electrolab.fr.
Si la doc ne peut être atteinte (directement ou non) depuis la page d'accueil, elle est considérée comme inexistante.
Une doc est considéré atteignable même si elle n'est pas nécessairement accessible au public depuis internet.
Pour les projets personnels, il n'y a bien évidemment aucune obligation d'appliquer cette règle, mais il y a une section membres pour permettre d'y recenser les projets de chacun. TODO: ajouter la section membres.
Le principe de cette règle est donc d'avoir une arborescence qui part de la page d'accueil, pour avoir une documentation qui se veut exhaustive.
C'est important pour limiter la quantité de connaissance cachée, inaccessible pour les nouveaux membres.
La doc peut être directement une page sur ce même wiki, ou bien un lien vers une doc hébergée ailleurs, comme gitlab ou autre. Ça peut être aussi un lien vers une doc officielle s'il s'agit d'un produit public, bien qu'il soit quasi-systématiquement nécessaire de rajouter quelques infos spécifiques à l'utilisation au sein du lab.
"C'est comme dans ton frigo: si c'est périmé, faut jeter"
Toute documentation a tendance au fil du temps à accumuler des chapitres et des liens, mais on fait rarement le travail de supprimer les liens concernant des procédés ou des outils qui n'existent plus ou ont totalement changé.
Il faut s'assurer qu'on ne garde la documentation pertinente par rapport à ce qui se fait au moment présent.
La doc des outils dont le lab s'est débarassé doit être supprimée, ou déplacée dans une section archive qui n'est pas accessible directement depuis la page d'accueil, pour la garder à jour sans superflu.
Et bien entendu, il faut essayer de garder à jour le contenu quand il n'est pas totalement obsolète, mais c'est assez évident, et plus facile à dire qu'à faire. TODO: réfléchir à des mécanismes pour faire une revue régulière de la doc.
En contre-exemple: le vieux wiki de la v1 du lab est devenu trop fouilli à force d'accumuler des pages devenues non pertinentes, mais poutant toujours indexées depuis la page d'accueil. Résultat: après avoir cliqué plusieurs fois, on constate pifométriquement que 3 pages sur 4 sont obsolètes. On en déduit alors qu'il n'y a pas d'info à jour, et que si on faisait l'effort de mettre à jour, les visiteurs ne pourront même pas facilement distinguer une information valable d'une info obsolète.
Dans la pratique, l'obsolecence a rendu la documentation inutilisable et non maintenable, ce qui accentue l'obsolescence. L'effet de dégradation n'est pas linéaire mais s'aggrave plutôt avec le temps, d'où l'importance de ne pas hésiter à "trancher dans le vif". De toutes façons, les outils gardent souvent un historique des changements, et on peut revenir en arrière (cf règle sur l'initiative)
Rapport signal bruit
TODO Pas de def mais au moins l'éclatement des sigles acronymes pour découvrir le sens
Blame / date
Exemple PVC laser cutter
Ne pas hésiter à supprimer.
L'idée de ce document est d'établir un système pour pérenniser la connaissance qui est répartie dans les têtes des membres existants, et la coucher sur papier électronique, de telle façon que tout membre puisse avoir une utilisation efficace du lab, et qu'on ait une photographie.
Ce n'est pas: un support à compte-rendus de réunion, ou autre doc du quotidien.
Dans ce contexte il peut y avoir des modifications / réorganisation pour garder en vue l'objectif d'une documentation efficace du lab