2023-09-13 - Documentation.md 5.4KB
Documentation
[en] The deeper I dig into my research, the more case studies and examples I find. Institutional memory is frequently overlooked and undervalued - until the moment when someone needs access to memory right now, and of course by then it’s too late. Good remembering means turning tacit knowledge into explicit knowledge; ==if all your tacit knowledge has left the building inside the heads of former colleagues, it’s lost to you forever.==
So I think there’s a case for allowing and encouraging documentation for teams, just as much as documentation for software. Writing that documentation is a task, It needs to be part of someone’s job. Every organisation needs a little bit of storytelling capability, to help make that job easier.
J’ai développé un outil pour Scopyleft l’année dernière qui s’intitule « Le Voilier ». Il s’agit d’un lieux où l’on consigne nos discussions, propositions et résolutions. C’était important car il y avait pas mal de perte/dilution d’information orale, ce qui est classique en équipes distribuées qui grandissent. Depuis un an et demi, il y a 381 sujets qui ont été consignés dans ce journal de bord collectif, c’est un outil vivant. Des fonctionnalités bourgeonnent ou passent au compost au gré des besoins, c’est assez plaisant d’avoir la flexibilité de connaître le générateur du site (350 lignes de Python à ce jour) et de pouvoir sortir du cadre sans que ce soit trop douloureux.
Cela a commencé avec un site totalement statique qui était (re)construit par l’intégration continue à chaque ajout de fichier markdown avec les bonnes méta-données dans un dossier dédié. Classique. C’était facile pour les personnes familières de git(lab) mais moins pratique pour celles qui ne le sont pas, notamment lorsqu’il faut prendre des notes en séance. L’expérience utilisateur·ice des forges logicielles n’est pas vraiment adaptée à un tel usage, surtout dans un contexte de charge cognitive élevée.
J’ai donc transformé cela en site semynamique 🌱 : on reste sur la même infrastructure mais je rajoute un formulaire (toujours statique) qui va soumettre les données vers une seule fonction Python/wsgi qui consiste à créer le fichier markdown conforme aux attentes de l’outil et à le pousser sur le dépôt. Cela a rendu l’outil plus accessible et avenant. Depuis, j’ai décliné ce principe pour d’autres scenarii avec de bons retours.
Avec l’expérience et un petit script de déploiement, cela me prend moins d’une heure à mettre en place sur AlwaysData avec un strict minimum de maintenance. J’ai une relative tranquillité d’esprit aussi car seule une petite partie du site serait inutilisable si le service tombait et il reste la possibilité d’ajouter des fichiers dans git à la main s’il y avait une urgence.
Je ne sais pas trop quoi faire à partir de là, je me dis que ça pourrait en inspirer d’autres. Entre les sites purement statiques et les usines à gaz en JS, il y a tout un dégradé de couleurs enthousiasmantes, certaines restant à découvrir !
Peut-être qu’à un moment, on pourrait aussi proposer un catalogue d’outils utiles aux coopératives — à l’instar de Paheko pour les associations…
🏡 Une grande partie de mon entourage est déjà propriétaire. Ça en dit long sur la sphère dans laquelle j’évolue. J’ai l’impression que le fait d’acheter une maison fait partie de la liste non-négociable d’une vie réussie dans notre monde capitaliste. Jusqu’à très récemment, je n’avais jamais interrogé ce postulat.
*Propriété par Fanny Cheung* (cache)
[en] 🔨 Yes, it’s fair to point out that AI in its many different software manifestations can be considered a tool. But that is not the point of the statement. The word to watch out for is “just”. If someone were to say ”it’s a tool”, that makes sense. But the word “just” is there to shed accountability.
Hence my concern is that the statement itself removes accountability and consideration for the bigger picture effects. ==Saying something is just a tool creates the faulty mental model== of all tools having interchangeable qualities from an ethical perspective, which simply isn’t true.
*If a hammer was like AI…* (cache)
[en] 💯 When it comes to front-end development, I’m worried that we’ve reached a state where the more complex over-engineered approach is viewed as the default.
I may be committing a fundamental attribution error here, but I think that we’ve reached this point not because of any consideration for users, but rather ==because of how it makes us developers feel.== Perhaps building an old-fashioned website that uses HTML for navigations feels too easy, like it’s beneath us. But building an “app” that requires JavaScript just to render text on a screen feels like real programming.