PD-232 — Retour d'expérience¶

1. Résumé exécutif¶

La User Story PD-232 visait à structurer une FAQ maintenable via Markdown en utilisant les Content Collections d'Astro. L'implémentation est la plus réussie de l'EPIC : schéma Zod complet avec catégories, ordre et langue, 54 fichiers FAQ Markdown (27 FR + 27 EN) organisés par catégorie, rendu avec accordéons <details> accessibles, et schéma JSON-LD FAQPage généré dynamiquement. Seuls deux écarts mineurs ont été identifiés : validation Zod légèrement moins stricte que prévu et composant FAQSection non factorisé. Verdict : ACCEPTÉ AVEC RÉSERVES (écarts mineurs uniquement).

2. Points fluides¶

• Content Collection configurée avec schéma Zod complet (question, category, order, lang, translationKey)
• Enum de catégories stricte (security, legal, business, usage, apps, transfer, data, misc)
• 54 fichiers FAQ Markdown créés et organisés par langue et catégorie
• Frontmatter validé automatiquement au build (erreurs bloquantes)
• getCollection() avec filtre par langue fonctionnel
• Tri par order et regroupement par catégorie implémentés
• Accordéons <details> HTML natifs (accessibles sans JS)
• Schéma JSON-LD FAQPage généré dynamiquement avec toutes les questions
• Styles de réponse FAQ bien formatés (listes, blockquotes, strong)
• Animation d'ouverture CSS fluide

3. Points difficiles¶

• Validation Zod minimale : Le schéma utilise z.string() pour question au lieu de z.string().min(10) prévu dans le plan. Des questions très courtes pourraient passer.

• Composant FAQSection non créé : Le plan prévoyait un composant dédié FAQSection.astro pour factoriser le rendu des accordéons. L'implémentation a choisi de tout mettre inline dans les pages FR et EN.

• Duplication FR/EN : Les pages faq.astro FR et EN sont quasi identiques. Un composant partagé aurait réduit la duplication.

4. Hypothèses révélées tardivement¶

• Pas besoin de script validate-faq.sh : La validation Zod au build détecte automatiquement les frontmatters invalides. Le script de parité FR/EN prévu dans le plan n'a pas été jugé nécessaire.

• Markdown body brut dans JSON-LD : Le schéma FAQPage utilise entry.body (Markdown brut) au lieu du HTML rendu. Les moteurs de recherche gèrent bien ce format.

• translationKey peu utilisé : Le champ optionnel existe dans le schéma mais n'est pas exploité pour lier les versions FR/EN programmatiquement.

5. Invariants complexes¶

6. Dette technique¶

7. Risques résiduels¶

8. Améliorations processus¶

• Créer un composant partagé pour éviter la duplication des pages FR/EN
• Exploiter translationKey pour générer automatiquement les liens hreflang FAQ↔FAQ
• Ajouter un test de parité CI pour alerter si une FAQ existe en FR mais pas en EN
• Documenter le workflow d'ajout de FAQ pour les contributeurs non-techniques

9. Enseignements clés¶

1. Les Content Collections sont puissantes — La validation Zod intégrée et le typage automatique éliminent beaucoup d'erreurs potentielles.

2. L'enum Zod est un garde-fou efficace — Impossible de créer une FAQ avec une catégorie inexistante, le build échoue immédiatement.

3. <details> est suffisant pour les accordéons — Pas besoin de JavaScript custom pour un comportement d'accordéon accessible et fonctionnel.

4. La factorisation peut attendre — Avoir du code inline dupliqué est acceptable pour un MVP si le résultat fonctionne. Le refactoring viendra plus tard.

5. Le JSON-LD FAQPage améliore le SEO — Générer dynamiquement le schéma à partir des données garantit qu'il est toujours à jour avec le contenu.

10. Addendum — Résolution des écarts (2025-12-21)¶

Mise à jour : Les écarts E-01 et E-02 identifiés dans ce REX ont été corrigés. Le verdict passe de "ACCEPTÉ AVEC RÉSERVES" à "✅ ACCEPTÉ".

Corrections apportées¶

Impact sur les sections précédentes¶

Métriques de refactoring¶

Référence¶

• Acceptabilité : PD-232-acceptability.md — Suivi E-01/E-02 du 2025-12-21
• Fichiers modifiés :
• src/content/config.ts
• src/components/FAQSection.astro (créé)
• src/pages/fr/faq.astro
• src/pages/en/faq.astro

Verdict final : ✅ ACCEPTÉ (2025-12-21)