Rédiger la documentation d'un système de design et la tenir à jour

## Décider ce que couvre la documentation, des principes aux composants Documentez à la fois les fondements immatériels du système — principes, décisions et méthodes de travail — et ses ressources tangibles : modèles, composants, règles d'utilisation et outils de mise en œuvre. Rendez le périmètre visible avant de rédiger afin que les omissions deviennent des éléments du carnet de travail plutôt que des surprises. ## Découper la documentation en pages et commencer là où ça bloque le plus Décomposez le travail en pages autonomes. Traitez en priorité les domaines qui causent le plus de difficultés, puis les composants fréquemment utilisés ou comportant de nombreuses dépendances. Suivez l'avancement et réexaminez les priorités lorsque les contraintes évoluent. Utilisez tout outil que l'équipe peut maintenir, parcourir et partager de manière fiable. ## Expliquer chaque composant en répondant à quatre questions Pour chaque composant, répondez à quatre questions : Qu'est-ce que c'est, y compris ses états et ses options ? Pourquoi le choisir plutôt que des solutions similaires ? Dans quel contexte est-il approprié ? Comment doit-il être utilisé, notamment avec quelles variantes prises en charge, quels exemples et quelles recommandations ou interdictions explicites ? ## Écrire d'abord pour le design et le développement, et résumer pour les autres Répondez d'abord aux besoins des designers et des développeurs avec un comportement clairement décrit, des critères de décision, des références de mise en œuvre et des liens vers le code ou les récits de composant. Offrez aux rôles produit, QA et recherche un chemin de vérification plus court. Réutilisez les modèles solides d'autres systèmes, mais adaptez-les ; l'accès fonctionnel compte davantage que la perfection visuelle. ## Avant chaque sortie, vérifier que documentation, design et code concordent Traitez la documentation comme un produit vivant. Examinez les nouveaux composants et les recommandations lors des séances de critique, évaluez les besoins de documentation au lancement du projet, testez les composants avec des utilisateurs et des contrôles d'accessibilité, puis vérifiez l'alignement entre design, code et documentation avant chaque version. Modifiez les pratiques régulières de maintenance lorsque les preuves montrent qu'elles ne fonctionnent pas.