Mon carnet de bord technique : ce que j'y note chaque jour

En 2021, j'ai passé trois heures à déboguer un problème de connexion Postgres sur Railway. Env var mal configurée, erreur de timeout, message générique qui ne pointait vers rien d'utile. Je l'ai réglé. Deux mois plus tard, même projet, même symptôme, je recommence le débogage à zéro. J'avais complètement oublié comment j'avais réglé le problème la première fois.

C'est ce jour-là que j'ai commencé à tenir un carnet de bord technique développeur. Pas par discipline. Par fatigue de refaire le même travail deux fois.

Trois ans plus tard, ce journal de bord développeur est devenu l'outil que j'ouvre le plus souvent après mon éditeur de code. Voici comment il fonctionne, ce que j'y mets, et les erreurs que j'ai faites en le construisant.

Pourquoi j'ai commencé

Avant le carnet, ma mémoire externe c'était mon historique de terminal et mes messages Slack à moi-même. Autant dire rien de fiable.

Le vrai déclic, ce n'est pas juste le temps perdu. C'est la crédibilité. J'ai eu un client freelance qui m'a demandé pourquoi j'avais mis deux jours à régler un bug que j'avais déjà réglé sur un projet similaire six mois avant. Je n'avais pas de bonne réponse. J'avais juste oublié.

Ça m'a forcé à réaliser un truc simple : le code que j'écris, je peux le retrouver dans Git. Les décisions que j'ai prises et pourquoi, elles, disparaissent si je ne les note pas. Un commit me dit ce que j'ai changé. Il ne me dit jamais pourquoi j'ai abandonné trois autres approches avant.

J'ai attaqué mes erreurs d'acquisition en freelance à peu près à la même période, et le pattern était identique : je répétais les mêmes erreurs parce que je ne les documentais jamais. J'en parle plus en détail dans mon article sur les 5 erreurs d'acquisition qui ont failli tuer mon freelancing. Le carnet de bord et la documentation d'erreurs business, c'est le même réflexe appliqué à deux domaines différents.

Ce que je note concrètement

Mon carnet n'est pas un journal intime de code. Je n'y écris pas « aujourd'hui j'ai codé une API ». C'est inutile et personne ne relit ça, moi le premier.

Ce que je consigne réellement :

• Décisions d'architecture : pourquoi j'ai choisi FastAPI plutôt que Django pour tel projet, avec les contraintes qui ont motivé le choix (charge attendue, équipe solo, besoin d'async natif).
• Commandes obscures : celles qu'on tape une fois par trimestre et qu'on ne mémorise jamais. La ligne exacte pour reset une migration Alembic cassée, le flag Docker qu'il faut absolument passer sur Railway pour éviter un timeout de build.
• Erreurs résolues avec la cause exacte, pas juste le symptôme. « Erreur 502 sur endpoint X » ne m'aide pas six mois plus tard. « Erreur 502 causée par un worker Gunicorn qui timeout à 30s sur un appel Claude API non streamé » me sauve une après-midi.
• Pistes abandonnées et pourquoi. C'est la section la plus sous-estimée. Si j'ai testé une approche et que je l'ai laissée tomber, je note la raison. Sinon, six mois plus tard, je retombe sur la même mauvaise idée et je la teste à nouveau en pensant que c'est neuf.

J'ai fait cette erreur exacte en optimisant une API FastAPI : j'avais déjà testé un système de cache Redis mal configuré qui aggravait la latence au lieu de l'améliorer. Sans note, j'aurais retesté la même config six mois après. Les détails techniques de cette optimisation, je les ai mis dans mon guide sur les meilleures pratiques FastAPI, mais la leçon « note pourquoi t'as abandonné une approche » vient directement de mon carnet.

Ce que je n'y mets jamais : du code entier copié-collé. Le code, il est dans Git ou dans un snippet manager. Le carnet, c'est le contexte autour du code, la partie que Git ne capture pas.

Mon système d'organisation

J'ai testé plusieurs formats avant de trouver celui qui tient dans le temps. Le format daté (genre journal quotidien classique) a échoué chez moi après trois semaines. Trop chronologique, impossible à chercher efficacement.

Ce qui fonctionne pour moi : sections par projet, avec un index de recherche rapide en tête de document.

Concrètement :

• Un fichier Markdown par projet actif (je suis passé de Notion à Obsidian, mais franchement le format compte moins que la discipline)
• Dans chaque fichier, des sous-sections thématiques : Architecture, Bugs résolus, Commandes, Décisions abandonnées
• Un fichier index global qui liste les mots-clés et pointe vers les entrées pertinentes (« timeout Railway → projet X, section Bugs, 12 mars »)

Le format thématique bat le format daté pour une raison simple : quand je cherche une info, je cherche par symptôme ou par technologie, jamais par date. Personne ne se souvient « c'était un jeudi de novembre » mais tout le monde se souvient « c'était le bug avec les migrations Alembic ».

L'index de recherche rapide, c'est l'ajout le plus rentable que j'ai fait. Sans lui, j'ai un carnet de 40 pages et je scroll pendant dix minutes pour retrouver une commande. Avec lui, ctrl+F sur deux ou trois mots-clés et j'ai ma réponse en quinze secondes.

C'est le même principe que j'utilise pour structurer du contenu en SEO programmatique : sans un système d'organisation clair, l'information existe mais devient inutilisable. J'ai documenté mes erreurs les plus coûteuses là-dessus dans SEO programmatique : mes erreurs à 50k$. Un carnet mal organisé, c'est la même chose qu'un site mal structuré : le contenu est là, mais personne (même pas toi) ne le retrouve.

D'ailleurs, si le sujet t'intéresse côté contenu et pas juste côté carnet personnel, TokamDarius documente pas mal ce genre de systèmes d'organisation appliqués au SEO et à la production de contenu. C'est le même réflexe : structurer l'info pour qu'elle serve plus tard, pas juste la produire.

Les erreurs à éviter

J'ai fait toutes celles-là, dans l'ordre.

Trop de détails inutiles. Ma première version du carnet ressemblait à un log system verbeux. Je notais chaque commande git, chaque petit refactor, chaque renommage de variable. Résultat : 200 lignes de bruit pour 5 lignes utiles. La règle que j'applique maintenant : je note seulement ce que je risque d'oublier ET qui m'a coûté du temps à comprendre. Si c'était évident sur le coup, ça n'a pas sa place dans le carnet.

Pas assez de contexte. L'erreur inverse, tout aussi fréquente. J'écrivais des trucs du genre « fix: changé le port à 8080 » sans dire pourquoi ni dans quel contexte. Six mois plus tard, cette note ne veut plus rien dire. Une bonne entrée répond à trois questions minimum : quel était le symptôme, quelle était la cause réelle, qu'est-ce que j'ai changé pour régler ça. Sans ces trois éléments, l'entrée est décorative.

Absence de relecture régulière. Celle-là, c'est la pire parce qu'elle rend tout le reste inutile. J'ai eu des mois où j'écrivais dans le carnet sans jamais le relire. Autant ne pas l'avoir. Ce qui a changé la donne : un rituel de 15 minutes chaque vendredi où je relis les entrées de la semaine et je les nettoie ou je les déplace dans la bonne section du projet. Sans ce rituel, le carnet devient une décharge à idées, pas un outil de travail.

Trop de plateformes différentes. J'ai éparpillé mes notes entre Notion, un fichier texte local, et des commentaires dans le code pendant presque un an. Résultat : je ne savais jamais où chercher. Un seul endroit, même imparfait, bat trois endroits parfaits que tu n'ouvres jamais.

Ce que ça change vraiment

Le bénéfice le plus concret, c'est la vitesse de résolution de bug. Un problème déjà rencontré, je le règle en quelques minutes au lieu de recommencer une session de débogage complète. Ce n'est pas marginal sur un an de travail solo.

L'autre bénéfice, moins évident au départ : le carnet m'aide à prendre de meilleures décisions d'architecture, parce que je peux relire pourquoi j'ai fait tel choix sur un projet passé. Quand j'ai comparé Claude Code et ChatGPT Codex sur plusieurs projets, mes notes de carnet m'ont servi de base factuelle plutôt que de me fier à mon impression du moment. Les résultats complets sont dans mon comparatif Claude Code vs ChatGPT Codex, mais l'idée derrière, c'est que sans notes datées et précises, ce genre de comparaison devient de l'opinion pure plutôt que du retour d'expérience.

Un carnet de bord, ce n'est pas un exercice de discipline pour la discipline. C'est un outil qui rembourse son coût d'entretien dès la première fois où tu retrouves une solution en trente secondes au lieu de la refaire en trois heures.

Une action concrète pour demain

Ouvre un fichier Markdown, mets un titre de projet en haut, et note la prochaine erreur que tu résous aujourd'hui : le symptôme exact, la cause réelle, et ce que tu as changé. Une seule entrée. Pas de système parfait, pas de template complexe. Juste cette entrée-là.

Le système, tu le construiras en avançant. La discipline de base, elle, commence dès la première note honnête.

---

À lire aussi

• Optimiser les performances d'une API FastAPI : Guide des meilleures pratiques
• Automatiser le déploiement continu d'applications iOS avec CI/CD : Un guide étape par étape
• Les outils essentiels pour une stratégie de SEO programmatique réussie en 2026