Rédiger la documentation de votre maison
(luke.hsiao.dev)- Les primo-accédants ont souvent du mal à retrouver des informations comme les équipements, l’historique des réparations, les modèles de produits ou la façon de couper certaines installations, d’où l’idée qu’une maison a elle aussi besoin d’un manuel utilisateur de type documentation technique
- La documentation de la maison peut être structurée comme Diátaxis, en tutoriels, guides pratiques, références techniques et explications, ce qui facilite le classement selon la nature des questions
- En ajoutant un journal des modifications à ces quatre types de documentation, on peut suivre des travaux comme des réparations de plomberie, des modifications du système d’irrigation, la pose de moquette ou des rénovations, ainsi que leurs coûts
- La mise en œuvre peut rester simple, avec un classeur manuscrit ou un Google Doc, mais cet exemple montre la création d’un site de documentation consultable avec Astro Starlight, un dépôt git et Cloudflare Pages
- La famille peut retrouver les informations nécessaires en un seul endroit, et pour le propriétaire suivant, transmettre seulement les fichiers source en Markdown reste déjà bien mieux que de n’avoir aucun historique
Une maison aussi a besoin d’un manuel utilisateur
- Lorsqu’on devient propriétaire pour la première fois, il arrive souvent qu’il soit difficile de retrouver immédiatement les informations de base sur la maison
- Voici les questions qui se sont réellement posées
- Quand la moquette a-t-elle été posée ?
- Comment couper l’arrivée d’eau principale ?
- Comment le système d’irrigation est-il configuré ?
- Où se trouvent les têtes d’arrosage ?
- Quel est le modèle du lave-vaisselle et où trouver son manuel utilisateur ?
- Pourquoi la pression d’eau est-elle élevée ?
- Quelle entreprise gère les eaux usées ?
- Comment les circuits électriques de la maison sont-ils répartis ?
- Y a-t-il un câblage réseau ?
- Quelle est exactement la couleur de la peinture ?
- Quel modèle de filtre HVAC faut-il acheter ?
- La plupart de ces questions n’avaient pas de réponse, ou il a fallu enquêter et faire de la rétro-ingénierie soi-même
- Réunies au même endroit, ces informations deviennent une base de connaissances que la famille peut consulter au besoin, comme une bonne documentation logicielle
Structurer la documentation de la maison avec Diátaxis
- On peut aussi appliquer à la documentation d’une maison le framework de documentation technique Diátaxis
- Diátaxis divise la documentation en quatre modes
- tutoriels
- guides pratiques
- références techniques
- explications
- En classant les questions liées à la maison selon ces catégories, il devient plus facile de distinguer « ce qu’il faut faire » de « pourquoi c’est ainsi »
Conserver l’historique de la maison avec un journal des modifications
- Les quatre catégories de Diátaxis ne suffisent pas à elles seules à refléter tous les changements qu’une maison connaît avec le temps, d’où l’ajout d’une page de journal des modifications
- Même si l’on ne peut pas répondre à toutes les questions sur le passé, on peut au moins consigner les principaux changements survenus pendant la période de propriété
- Le journal des modifications peut contenir des éléments comme
- les réparations de plomberie et leur coût
- les mises à niveau et modifications du système d’irrigation
- la pose de moquette
- les rénovations
- Cela permet de répondre plus facilement à des questions comme « Quand cette moquette a-t-elle été refaite, quelle surface a été nécessaire et combien cela a-t-il coûté ? »
De la simple reliure au site web, plusieurs options sont possibles
- La documentation d’une maison n’a pas besoin d’être construite avec une stack technique complexe
- un classeur de notes manuscrites
- un Google Doc
- une chaîne YouTube regroupant de courtes vidéos
- un site web consultable depuis un téléphone
- Ce site de documentation pour la maison est réalisé avec Astro Starlight
- Les documents sont stockés dans un dépôt git dédié à la maison, avec une configuration de build et de déploiement automatiques via Cloudflare Pages
- Le même dépôt git sert aussi d’emplacement pour conserver d’autres documents importants liés à la maison
Ressources à conserver dans le dépôt
- L’arborescence de répertoires présentée montre l’étendue des ressources qui peuvent être incluses dans le dépôt de documentation de la maison
- On peut y conserver notamment
- les contrats et documents de closing
- des plans, schémas de bureau, wireframes du jardin et autres diagrammes
- les fichiers du site de documentation basé sur Astro Starlight
- des documents financiers
- un guide pour les invités et les informations Wi-Fi
- le rapport d’inspection du logement
- les polices d’assurance
- les documents de taxe foncière
- les documents liés à la location Internet
- À l’intérieur du site de documentation, on peut organiser des sections comme le journal des modifications, des guides, une présentation et des documents de référence
Une valeur durable pour la famille et le prochain propriétaire
- La documentation de la maison devient un point d’accès unique pour retrouver les informations et améliore la qualité de vie de la famille
- La page de référence sur le système d’irrigation est souvent utile pour comprendre son fonctionnement
- La page de référence des manuels utilisateur rassemble les liens vers les manuels PDF ou en ligne des appareils électroménagers et électroniques
- Quand il faut nettoyer régulièrement le lave-vaisselle, il suffit de quelques clics pour accéder au manuel, sans devoir retrouver ou rechercher à nouveau le numéro de modèle
- Le guide expliquant comment couper l’arrivée d’eau principale apporte de la sérénité en cas d’urgence
- Le journal des modifications permet de vérifier facilement quand un travail a été effectué et combien il a coûté
- Même si le propriétaire suivant ne souhaite pas d’une stack technique complexe, partager uniquement les fichiers Markdown en texte brut utilisés pour générer le site reste bien mieux que de ne laisser aucun historique
1 commentaires
Commentaires Hacker News
C’est arrivé à un ami. Il vivait dans une vieille maison et, pendant la pandémie, il enchaînait sans fin les chantiers de réparation ; le soir, il faisait souvent des lives de rénovation pour garder le contact avec les gens.
Un jour, en démolissant un mur de la salle de bains, il a trouvé entre deux cloisons un presse-papiers avec une note attachée. Il a commencé à la lire, puis s’est mis à pleurer. C’était une liste de câblage et de plomberie datant des années 1970, et sur la première page figurait ce mot : « Les réparations sont difficiles et parfois solitaires, mais continuez ; un jour, ça en vaudra la peine. »
À un moment particulièrement solitaire de la pandémie, il était tombé exactement quand il en avait besoin sur la documentation et les encouragements laissés par quelqu’un 50 ans plus tôt. C’était un très beau moment.
C’étaient des échanges chaleureux et sincères entre des membres de la famille partis en Californie et ceux restés du côté de l’Oklahoma ; mon oncle dit qu’il a la gorge serrée chaque fois qu’il les relit.
Dans Amélie, en apprenant la mort de la princesse Diana, le bouchon de parfum qu’elle laisse tomber heurte un carreau mural, révélant une boîte métallique contenant des objets d’enfance d’un garçon qui vivait dans l’appartement des décennies auparavant.
https://en.wikipedia.org/wiki/Am%C3%A9lie
Dans Being John Malkovich, Craig découvre une petite porte cachée en classant des dossiers, rampe dans un tunnel et pénètre dans la conscience de l’acteur John Malkovich.
https://en.wikipedia.org/wiki/Being_John_Malkovich
Dans A Ghost Story, une femme désignée par « M » raconte à son mari musicien, « C », que lorsqu’elle était enfant et déménageait souvent, elle cachait de petits mots dans chaque endroit où elle vivait.
https://en.wikipedia.org/wiki/A_Ghost_Story
Pendant que toute la maison était quelque part entre démolition et reconstruction, j’ai aménagé à la perfection la plus petite pièce, 2 × 2 mètres, pour en faire un refuge ; c’est cette pièce qui m’a permis de garder la tête hors de l’eau.
La plupart des solives de plancher s’étaient effondrées ou avaient pourri et devaient être remplacées ; à un moment, la maison n’était plus qu’un volume vide avec seulement le toit et les étais des murs. Il aurait sans doute été plus rapide et préférable de tout raser pour reconstruire, mais j’avais décidé de conserver l’aspect extérieur sans changement visible, à part l’ajout d’une fenêtre de toit sur le pan de toiture.
Depuis, j’ai encore fait deux gros chantiers dans d’autres maisons, mais ma passion pour ce genre de travaux est désormais presque épuisée.
Dans ma précédente maison, j’avais mis en place pendant des années de la domotique smart home et j’avais préparé un classeur avec des instructions claires pour tout, les reçus des upgrades, les garanties, des QR codes pour télécharger les apps, un plan du terrain, des plans d’étage et une liste de contacts d’artisans.
J’y ai passé des dizaines d’heures, y compris à faire de courtes vidéos YouTube pour montrer comment couper l’eau, fermer les robinets extérieurs et l’arrosage, appairer les appareils, etc. J’avais le sentiment d’assurer une « passation chaleureuse » de la maison.
Mais les nouveaux propriétaires ont revendu la maison deux ans plus tard et, en voyant les photos de l’annonce, j’ai constaté qu’ils avaient arraché la plupart des équipements smart home et fait une rénovation bâclée. Les vidéos YouTube affichaient toujours 0 vue, et il semblait très peu probable qu’ils aient même consulté le classeur que je leur avais laissé.
Je ne consacrerai plus jamais autant d’efforts à documenter une maison ; désormais, je ne laisse que juste assez de documentation pour qu’on comprenne ce que j’ai fait.
En pratique, je n’achète pas les choses annoncées comme « uniques au monde ». Même si elles sont belles, je sais que ce sera pénible de s’en débarrasser.
À mes yeux, les équipements tape-à-l’œil et sophistiqués n’ajoutent pas de valeur ; au contraire, ils en retirent, parce qu’ils augmentent le travail de démontage. Je préfère une maison avec une cuisine IKEA basique : elle est facile à remplacer et, selon les cas, pratique à utiliser telle quelle.
C’était un dossier de plusieurs centaines de pages, avec non seulement les défauts trouvés, mais aussi les réparations recommandées, un calendrier d’entretien continu, des photos de l’emplacement de la vanne d’arrêt d’eau, quelques vidéos et même une inspection vidéo de la canalisation d’égout.
J’ai commencé à mettre à jour ce que j’ajoutais ou modifiais, puis je me suis dit que, le jour de la vente, il serait plus simple de faire appel à nouveau à un inspecteur. Cela dit, il n’y avait pas d’appareils connectés ; s’il y en avait eu, cela aurait peut-être coûté plus cher.
Ils imaginent une porte qui se verrouille, un intrus qui entre, ou le chauffage qui surchauffe ou sous-chauffe pendant des semaines alors qu’ils sont en voyage, et ils ne veulent tout simplement pas s’en mêler.
On pourrait vivre avec un simple indicateur à flotteur, mais il n’y avait aucune raison de ne pas utiliser un capteur de pression hydrostatique haute précision, un esp32, influxdb, grafana, spring, keycloak et mysql tournant sur AWS.
Cela dit, si je vends la maison, je n’aurai pas envie de recevoir des appels de support, donc je le retirerai probablement moi-même.
Moi aussi, si j’héritais d’équipements smart home, je les démonterais probablement pour la plupart, ou au minimum je les reflasherais avec un firmware open source.
Un autre principe important que j’ai appris : même si le Wi-Fi, les passerelles, HomeAssistant ou certains capteurs tombent en panne, la maison doit continuer à fonctionner normalement comme une maison idiote.
On entend souvent dire que même si l’on crée de la documentation, elle finit par être abandonnée, mais il existe aussi des contre-exemples.
J’ai acheté une maison restée vide après un divorce ; les deux anciens propriétaires avaient déjà déménagé depuis plusieurs mois, donc j’ai surtout eu affaire à l’agent immobilier.
Dans la maison, il y avait une carte « Félicitations pour votre nouvelle maison », une bouteille de vin pétillant et un classeur contenant tout ce qui concernait la maison. Il y avait les plans de construction, les plans à jour des modifications, l’emplacement de tous les câbles et raccordements, les manuels des équipements, factures et garanties, jusqu’à un croquis à la main de la disposition des plantes du jardin et des liens pour l’entretien de plantes exotiques.
Grâce à cette organisation laissée par l’ancien propriétaire, à chaque intervention sur les câbles ou petit chantier, les plans exacts m’ont fait gagner énormément de temps, et je lui en suis encore reconnaissant.
J’ai étiqueté pièce par pièce l’endroit où passent les tuyaux et les câbles, et je compte transmettre ça si je vends un jour. Je ne comprends pas pourquoi les constructeurs ne fournissent pas par défaut ce genre de jeu de photos de l’intérieur des murs ; en pratique, c’est très utile.
J’ai toute une pile de classeurs pour différents usages.
Après mon divorce en 2018, j’ai vendu ma maison de North Seattle. Je l’avais achetée en 2004, je travaillais alors chez Microsoft, et j’y ai élevé mon fils.
J’avais aussi construit moi-même un four en briques de 8×8×8 pieds pour les pizzas et le pain, et j’avais loué une excavatrice pendant une semaine pour creuser tout autour de la maison et installer un drain de fondation à 12 pieds de profondeur, des regards de nettoyage tous les 20 pieds, une conduite d’eau en pex de 2 pouces, ainsi qu’une ligne d’arrosage en pvc de 1 pouce à 3 pieds de profondeur. J’avais aussi entièrement mis à nu et rénové le sous-sol.
Dans un classeur de 3 pouces, j’avais tout documenté : lignes d’arrosage, drainage des fondations, système de recirculation gravitaire, câblage électrique, photos du projet de four en briques qui avait duré 6 mois, et même la façon de le déplacer si nécessaire.
Quand j’ai vendu la maison, je suis revenu en avion exprès pour le remettre en main propre au nouveau propriétaire et lui expliquer, mais il ne semblait pas particulièrement intéressé ni reconnaissant.
Il y a quelques mois, je suis revenu à Seattle, et mon fils de 17 ans, né dans cette maison, est allé demander s’il pouvait regarder l’extérieur ; ils l’ont regardé comme quelqu’un de bizarre, mais l’ont autorisé. À son retour, il m’a dit qu’ils avaient démoli le four en briques que j’avais imaginé survivre plus longtemps que moi.
J’espérais qu’un jour, dans 100 ans, des enfants mangeraient des pizzas sorties de ce four sans même savoir qui l’avait construit. Malgré tout, si j’ai à nouveau une maison, je documenterai encore tout ; simplement, je serai plus exigeant sur la personne à qui je la vendrai.
Vous avez construit et apprécié ce four, puis vous avez décidé de vendre la maison ; je ne comprends pas pourquoi vous voudriez ensuite décider de la façon dont les propriétaires suivants utiliseront la maison. Si vous vouliez laisser le four à pizza comme une sorte de monument à votre mémoire, il fallait conserver la maison.
Ce type de raisonnement fige les quartiers et pousse les habitants à vouloir contrôler l’apparence et l’ambiance du voisinage. Au final, cela mène à des règles qui empêchent les nouvelles constructions ou imposent même les couleurs de peinture.
On peut préserver des lieux historiquement importants, mais imposer à la majorité de conserver des détails mineurs qui ne comptent que pour quelques-uns pose problème. À l’inverse, on laisse parfois simplement pourrir des lieux qui ont une vraie signification historique.
https://www.theguardian.com/us-news/2018/mar/30/rosa-parks-h...
On ne peut pas s’attendre à ce que le nouveau propriétaire partage les centres d’intérêt de l’ancien. Il est peut-être sans gluten, ou n’a aucun intérêt pour la boulangerie. Difficile d’attendre de quelqu’un qu’il conserve 64 pieds carrés de jardin comme un monument pour quelque chose qui n’a pas de sens pour sa famille.
Je comprends l’attachement à une maison et le désir qu’elle tombe entre de bonnes mains, mais il ne faut pas s’attendre à ce qu’une nouvelle famille ne l’adapte pas à ses propres besoins.
Mais ce souhait s’accorde mal avec la culture résidentielle américaine, qui traite souvent les maisons comme des marchandises que l’on achète et revend fréquemment.
Mes parents aussi ont vendu leur maison il y a quelques années, et mon père dit souvent qu’elle lui manque et que les nouveaux propriétaires y font des changements affreux, mais cela ne change rien au fait que j’y ai grandi et que j’y ai passé de bons moments. Maintenant, mon père a l’occasion de créer de nouveaux souvenirs avec sa petite-fille dans sa nouvelle maison.
En réalité, il était bien en panne, mais j’ai remplacé la pompe et les capteurs, je l’ai bien nettoyé, et nous en avons profité pendant 8 ans. Quand nous avons vendu la maison, nous avons dit à l’acheteur que s’il n’en voulait pas, on pouvait négocier pour l’emmener dans notre nouvelle maison, mais il a acheté sans rien répondre.
Un voisin m’a dit qu’à peine installé, il avait détruit le jacuzzi et l’avait envoyé à la décharge. C’est bien sa maison, certes, mais certains gaspillent vraiment énormément.
On voit quelques commentaires disant que les documents transmis n’ont pas été appréciés, mais il existe aussi un autre point de vue. Pour ma première maison, j’ai acheté une maison qui avait besoin de travaux ; les précédents occupants étaient des parents décédés, et ce qu’ils avaient laissé, c’était un sac plastique contenant des manuels d’électroménager, de vieux reçus et, surtout, un tableau d’historique des réparations et remplacements.
Il indiquait les dates, ce qui avait été remplacé ou mis à jour, et combien cela avait coûté ; je n’ai donc pas eu à deviner l’âge de la clim ou de la chaudière, la date de rénovation du sous-sol, ni la quantité de moquette commandée pour la chambre secondaire. En tant que primo-propriétaire, cela m’a énormément aidé, et j’en suis très reconnaissant.
Sur la chaudière, j’ai noté au marqueur la date d’installation et les dates de maintenance ; sur la canalisation principale d’évacuation, j’ai écrit la date du dernier nettoyage, l’intervenant et l’emplacement du bouchon.
Une étiqueteuse industrielle rend ce genre de travail plus facile.
À l’époque, cela m’avait semblé très adulte et rare, mais c’est peut-être plus courant que je ne le pensais.
Quand j’ai fait construire ma maison, j’ai fait des scans Matterport avant et après la pose des plaques de plâtre, et c’est l’une des meilleures décisions que j’aie prises. C’est comme avoir une vision aux rayons X des murs.
C’est utile pour savoir où passent les câbles, combien il y a de montants entre les fenêtres quand on installe une TV, ou pour vérifier divers problèmes liés à l’électricité, au chauffage/climatisation et à la plomberie. Au début, je m’en servais chaque semaine ; maintenant que nous sommes installés, je l’utilise encore environ une fois tous les deux mois.
Je recommande aussi l’étiqueteuse de câbles Dymo Rhino 5200 et de la gaine thermorétractable. Si vous imprimez des étiquettes sur de la gaine thermorétractable et les mettez sur les fils, vous ne vous demanderez plus jamais où va tel câble. C’est aussi très pratique pour les faisceaux de câblage automobile : https://www.youtube.com/watch?v=-LcUQeTzIo4&t=66s
Je recommande toutefois la 5200 : https://www.amazon.com/DYMO-Industrial-RHINO-Label-1755749/d... - ce n’est pas un lien affilié
Ce lien contient le tag d’affiliation pmg097-20.
Voici l’adresse sans lien affilié : https://www.amazon.com/DYMO-Authentic-Industrial-RhinoPro-18...
Chaque fois que j’achète une maison, j’achète un petit carnet Moleskine que j’utilise comme carnet de la maison. J’y note les gros achats d’électroménager, les dates et numéros de série, une copie locale des informations du tableau électrique, les dates et coûts des rénovations, ainsi que des plans de pièces avec les dimensions.
J’y ajoute aussi les codes et finitions de peinture par pièce, moulure et plafond ; c’est extrêmement utile quand on doit réparer du placo et que les étiquettes des pots de peinture restants sont illisibles.
J’ai aussi créé des carnets séparés pour le déménagement et l’achat : ils contiennent les coordonnées du conseiller bancaire, de l’agent immobilier et de l’inspecteur, les rendez-vous, les prestataires, les grandes échéances, les check-lists d’emménagement et de départ, les listes d’objets à stocker, jeter ou donner, les dépenses, les documents administratifs à fournir, ainsi que les adresses et numéros de téléphone.
Avoir toutes ces informations immédiatement sous la main est assez puissant.
J’ai un camping-car, livré avec un gros manuel pour le châssis et un autre pour tous les équipements installés en usine. Je n’en suis pas le premier propriétaire, et mon frère, militaire très méticuleux, avait laissé la documentation de tous les appareils et dispositifs qu’il avait installés dans le camping-car.
Depuis que j’en suis propriétaire, je n’ai cessé d’apprécier cette documentation, et j’ai fait pareil pour le Wi-Fi, le réseau, l’abri à outils, le bureau assis-debout, le four, la plomberie, etc.
Depuis environ trois ans, j’applique le même principe à la maison : je tiens deux gros classeurs à anneaux, l’un pour le « châssis » de la maison, l’autre pour les équipements à l’intérieur.
J’y indique comment réinitialiser Internet, comment « redémarrer » le chauffe-eau, comment remplacer les filtres de clim, les références des filtres nécessaires, et même pourquoi la clim n’a pas de grille de reprise d’air, pour le prochain propriétaire comme pour moi-même. J’y inclus aussi l’historique de maintenance d’une section de canalisation d’eaux usées effondrée et remplacée, l’accès aux regards de nettoyage, les trajets des câbles dans les murs, le tableau électrique soigneusement étiqueté et les codes de peinture par mur.
Je commence par tout noter dans OneNote pour que ce soit consultable par recherche, puis je l’insère dans un classeur à 3 anneaux avec des sections par zone. Il ne faut pas essayer de faire bouillir l’océan d’un coup : en procédant par étapes, cela ne prend pas longtemps, et on s’en félicite pendant des années. Une maison ne change pas aussi vite qu’un logiciel développé par une équipe.
C’est vraiment très bien.
Il suffirait de remplir des champs en ligne pour générer un PDF.
Excellent conseil ; si vous êtes la personne de la famille qui gère principalement ce genre de choses, c’est aussi une bonne manière de se préparer à un décès soudain ou à une incapacité.
Mais les outils ou supports utilisés doivent être familiers aux gens ordinaires. Il faut partir du principe que la personne qui devra lire ça ne connaît git que dans le sens de « git ’er done! » de Larry the Cable Guy.
Pour le manuel du lave-vaisselle et les boulons de transport, il suffit de les scotcher sur l’appareil. Pour le chauffage, on peut fixer une feuille plastifiée sur la tuyauterie.
Si vous aimez le numérique, un document .docx dans un dossier en ligne partagé est probablement préférable ; dans 40 ans, on trouvera encore de quoi l’ouvrir et le modifier.
Pour certains, construire une stack numérique est une fin en soi, mais une documentation qui tient plusieurs décennies, j’ai du mal à y croire.
Par exemple, sur le boîtier de raccordement chez nous, les étiquettes des disjoncteurs sont écrites au marqueur, et les particularités des appareils ou les tailles de filtres sont notées sur place. L’information est visible exactement là où elle est nécessaire, et elle ne risque pas d’être supprimée ni cachée derrière un paywall.
Les gens de la tech compliquent parfois trop les choses.
J’habite dans la maison où j’ai grandi. Mon père a conçu lui-même le deuxième étage qu’il a ajouté.
Mon père connaît l’ossature de cette maison d’une manière que je ne pourrai jamais connaître et, même s’il vit maintenant à 50 miles de là, il reste une ressource formidable pour tout ce qui concerne la maison.
Il y a quelques années, quand j’ai voulu tirer du cat5 jusqu’au bureau du deuxième étage, il m’a dit : « Perce juste un trou dans le sol à cet angle. Il y a un vide qui va du deuxième étage jusqu’au sous-sol », et c’était bien le cas.
Ce que je voudrais, ce sont les plans qui sont dans la tête de mon père.
Maintenant, quand je veux faire quelque chose, c’est extrêmement utile, car je sais exactement à quoi ressemble la structure et où passent les conduites d’eau, les évacuations et les câbles électriques.
Chaque fois qu’on lui demande ce genre de chose, il doit sans doute rayonner intérieurement.