Aller au contenu principal

Template de tutoriel

Repères utiles
remarque

Ce template définit la structure minimale attendue pour chaque grand tutoriel du wiki. Il sert à maintenir une vraie qualité pédagogique et à garantir que le code reste lisible, expliqué et vérifiable.

Usage du template​

Ce modèle n'est pas là pour rigidifier l'écriture à l'extrême. Il est là pour éviter quatre dérives :

  • les tutoriels trop courts
  • les tutoriels trop théoriques
  • les tutoriels qui jettent du code sans contexte
  • les tutoriels qui oublient la vérification pratique

Template recommandé​

1. Titre clair​

Le titre doit dire immédiatement ce que le lecteur va construire ou comprendre.

Exemples :

  • API de base
  • Authentification avec FastAPI
  • Dockeriser une API FastAPI

2. Introduction​

Répondre rapidement à trois questions :

  • de quoi parle ce tutoriel ?
  • pour qui est-il écrit ?
  • qu'est-ce que le lecteur saura faire à la fin ?

3. Le problème concret à résoudre​

On part du besoin réel.

Exemples :

  • pourquoi a-t-on besoin d'une API ?
  • quel type de projet veut-on lancer ?
  • pourquoi une architecture même simple est déjà importante ?

4. Quand utiliser FastAPI pour ce cas​

Expliquer pourquoi FastAPI est pertinent ici.

À couvrir selon le sujet :

  • rapidité de mise en place
  • lisibilité
  • documentation automatique
  • typage Python
  • intégration facile avec Pydantic et SQLModel

5. Quand ne pas utiliser FastAPI pour ce cas​

Section indispensable pour éviter le tutoriel propagande.

Expliquer selon le sujet :

  • quand un besoin est trop simple
  • quand le framework ne répond pas bien au contexte
  • quand une autre approche peut être plus adaptée

6. Pré-requis​

Dire explicitement ce que le lecteur doit déjà connaître.

Exemples :

  • Python de base
  • terminal de base
  • notions simples de HTTP
  • notions simples de base de données

7. Vocabulaire indispensable​

Clarifier les mots qui peuvent bloquer.

Exemples :

  • endpoint
  • schema
  • model
  • session
  • dependency injection
  • service layer
  • JSON
  • async

8. Vision d'ensemble​

Avant d'entrer dans le détail, donner une vue globale du système.

Le lecteur doit comprendre :

  • quels sont les grands blocs
  • comment une requête circule
  • où vit la logique métier
  • où vit le stockage des données

9. Architecture type​

Décrire l'architecture retenue pour le chapitre.

Exemple pour ce wiki :

  • main.py
  • config.py
  • api/router.py
  • api/dependencies.py
  • api/schemas/
  • services/
  • database/

10. Structure du mini-projet​

Montrer l'arborescence avant le code.

Le lecteur doit pouvoir visualiser :

  • les dossiers
  • les fichiers clés
  • le rôle de chaque partie

11. Implémentation guidée avec code​

C'est le cœur du tutoriel.

Cette section doit désormais être considérée comme obligatoire pour les gros chapitres pratiques.

Elle doit montrer, étape par étape :

  • quelles commandes lancer
  • quels fichiers créer ou modifier
  • quel code écrire
  • pourquoi ce code est écrit ainsi
  • comment cela s'insère dans l'architecture générale

Important :

  • le code ne doit pas être jeté sans explication
  • chaque bloc doit être introduit pédagogiquement
  • le but n'est pas seulement de fournir du code, mais de montrer comment la solution se construit

12. Vérification guidée​

Après le code, montrer clairement comment vérifier que cela fonctionne.

Exemples :

  • lancer le serveur
  • ouvrir /docs
  • appeler un endpoint avec curl
  • vérifier la réponse JSON
  • confirmer l'écriture en base de données si nécessaire

13. Pièges et erreurs fréquentes​

Anticiper les erreurs classiques.

Exemples :

  • mauvaise variable d'environnement
  • oubli d'activer le venv
  • confusion entre modèle SQLModel et schéma Pydantic
  • oubli du commit() ou du refresh()
  • confusion entre route, service et base de données

14. Bonnes pratiques​

Transformer le tutoriel en guide de maturité.

Exemples :

  • garder les routes fines
  • centraliser la logique métier dans un service
  • rendre l'arborescence explicite
  • nommer les schémas selon leur rôle
  • séparer entrée, traitement et stockage

15. Variantes et évolutions possibles​

Montrer comment la solution peut grandir.

Exemples :

  • ajouter auth
  • ajouter tests
  • ajouter middleware
  • ajouter Docker
  • améliorer la gestion d'erreur

16. Checklist de validation​

Avant de fermer un gros chapitre pratique, ajouter une checklist courte et concrète.

Elle sert à vérifier que le lecteur sait réellement :

  • relancer l’exemple
  • expliquer les fichiers importants
  • rejouer le flux principal
  • identifier les points encore flous

17. Résumé final​

Le lecteur doit terminer avec une synthèse claire :

  • ce qu'il a construit
  • ce qu'il a compris
  • ce qu'il peut faire ensuite

18. Pour aller plus loin​

Cette section doit idéalement être la dernière du chapitre. Elle doit servir à router le lecteur, pas à relancer une nouvelle digression.

Bon minimum :

Checklist de validation avant publication​

Avant de considérer un tutoriel comme recevable, vérifier :

  • le problème concret est bien posé
  • le public visé est explicite
  • la valeur de FastAPI est expliquée
  • les limites sont mentionnées
  • le vocabulaire difficile est clarifié
  • l'architecture générale est visible
  • une arborescence de mini-projet est fournie
  • l'implémentation guidée avec code est présente
  • les commandes à lancer sont indiquées
  • la vérification guidée est présente
  • les pièges fréquents sont couverts
  • des bonnes pratiques sont données
  • des pistes d'évolution sont proposées
  • une checklist de validation utile est présente si le chapitre est pratique
  • si utile, la note renvoie vers le parcours de lecture ou la FAQ
  • le résumé final aide réellement à retenir l'essentiel
  • le Pour aller plus loin sert bien de sortie de chapitre, sans relancer une digression inutile

Signes qu'un tutoriel est encore trop faible​

Le tutoriel est encore insuffisant si :

  • il semble trop court pour son sujet
  • il parle d'architecture sans montrer les fichiers
  • il donne du code sans dire où le mettre
  • il montre du code sans dire pourquoi il existe
  • il oublie de montrer comment vérifier le résultat

Formule directrice​

poser le problème, construire l'intuition, montrer l'architecture, guider le code pas à pas, puis montrer comment vérifier et faire évoluer la solution