Comment écrire une fiche

La méthode : capturer, faire mûrir, réviser

1. Capturer — tout de suite, 5 minutes. Dès qu’on résout un problème ou qu’on apprend quelque chose, on crée une fiche avec draft: true et statut: graine. Trois lignes suffisent : le problème, ce qui a marché, la source. Règle : si j’ai cherché plus de 15 minutes, ou si je devrai le rechercher un jour, c’est une fiche.

2. Faire mûrir — chaque semaine, 30 minutes. On reprend les brouillons : reformuler avec ses mots, ajouter un exemple vécu, les tags, le type, le niveau, et surtout des liens vers d’autres fiches. Puis on retire draft.

3. Réviser — chaque trimestre. On relit les fiches anciennes, on fusionne les doublons, on corrige ce qui est devenu faux.

Trois règles d’écriture :

• une fiche = une idée : si le titre contient « et », ce sont deux fiches ;
• un titre qui affirme : « Préférer la composition à l’héritage » plutôt que « Héritage » ;
• écrire pour quelqu’un qui découvre, y compris soi-même dans deux ans.

Où ranger une fiche

Le dossier détermine la place dans la barre latérale. Une fiche vit dans un domaine, idéalement dans un sous-thème :

• Répertoiresrc/content/docs/

  • Répertoiretech/

    • index.mdx sommaire automatique du domaine
    • Répertoirejava/ un sous-thème = un dossier

      • index.mdx facultatif : donne son nom au sous-thème
      • records.mdx
  • Répertoiremethodes/

    • …
  • Répertoireeconomie/

    • …
  • Répertoireindustries/

    • …
  • Répertoireveille/

    • …
  • Répertoireparcours/ une page par parcours

    • …

• Un sous-thème apparaît dès que son dossier contient une fiche. Relancer npm run dev après la création d’un nouveau dossier.
• Pour lui donner un nom propre (« TypeScript » plutôt que « Typescript »), copier templates/sous-theme.mdx en index.mdx dans le dossier.
• Deux niveaux de dossiers suffisent. Au-delà, préférer les tags.

Le frontmatter

---
title: Préférer la composition à l'héritage   # obligatoire
description: Pourquoi, quand, et comment.      # obligatoire, une phrase
type: concept          # concept | pratique | reference | decision | retour-experience | lecture
level: intermediaire   # debutant | intermediaire | avance
statut: en-cours       # graine | en-cours | mure
tags: [conception, poo]
prerequis: [tech/conception/heritage]   # fiches à lire avant (chemin sans extension)
created: 2026-09-25
draft: true            # visible en local seulement
---

Un prérequis ou une étape de parcours qui pointe vers une fiche inexistante fait échouer le build avec un message explicite : pas de lien mort en production.

Les modèles

Modèle	Usage
templates/fiche.mdx	Toute fiche : concept, pratique, référence, lecture…
templates/decision.mdx	Une décision argumentée (format ADR)
templates/parcours.mdx	Un parcours de lecture
templates/sous-theme.mdx	La page d’accueil d’un sous-thème

cp templates/fiche.mdx src/content/docs/tech/java/records.mdx
npm run dev

Les composants disponibles (encadrés, onglets, blocs de code, diagrammes Mermaid…) sont décrits dans le modèle de fiche.