Articles avec le tag: Rédaction
L’accessibilité de la documentation ne se limite pas à la navigation et au contraste. Les exemples de code, les réponses JSON et les tableaux de référence doivent eux aussi rester clairs et utilisables sans dépendre uniquement de la couleur.
Une request techniquement valide n’est pas automatiquement un bon exemple. Utilisez des valeurs réalistes et des séquences qui révèlent le modèle de l’API et aident le developer à prévoir l’étape suivante. Un exemple dérivé d'un schema peut être syntaxiquement correct et n'enseigner presque rien.
Une approche pratique et vérifiable de « Une documentation d’authentification qui réduit les tickets de support », conçue pour une documentation claire et maintenable. Comment traiter « Une documentation d’authentification qui réduit les tickets de support » avec une approche pratique, vérifiable et maintenable de la documentation technique.
Une bonne liste de lecture n’est plus une étagère de classiques. Comparez les guides actifs de Microsoft, Google, GitHub et IBM, utilisez Diátaxis pour tester la structure et transformez chaque lecture en exercice concret.
Lire sur la documentation aide, mais les compétences progressent plus vite avec de petits exercices répétés de recherche, restructuration, édition et vérification accompagnés d’un feedback clair. « Améliorer mon technical writing » est trop large.
Une approche pratique et vérifiable de « Diagrammes as code : quand ils aident et quand ils n’aident pas », conçue pour une documentation claire et maintenable. Comment traiter « Diagrammes as code : quand ils aident et quand ils n’aident pas » avec une approche pratique, vérifiable et maintenable de la documentation technique.
Une approche pratique et vérifiable de « Documenter les erreurs API pour permettre la récupération », conçue pour une documentation claire et maintenable. Comment traiter « Documenter les erreurs API pour permettre la récupération » avec une approche pratique, vérifiable et maintenable de la documentation technique.
Une bonne documentation d’API associe contrat lisible par machine, explications humaines, exemples exécutables et comportement d’erreur explicite. La documentation REST s’adresse aux machines et aux humains.
Une approche pratique et vérifiable de « Exercices de révision pour progresser en rédaction technique », conçue pour une documentation claire et maintenable. Comment traiter « Exercices de révision pour progresser en rédaction technique » avec une approche pratique, vérifiable et maintenable de la documentation technique.
Une approche pratique et vérifiable de « Markdown à grande échelle : des conventions contre le chaos », conçue pour une documentation claire et maintenable. Comment traiter « Markdown à grande échelle : des conventions contre le chaos » avec une approche pratique, vérifiable et maintenable de la documentation technique.
Une description OpenAPI peut générer une référence précise, mais les developers ont toujours besoin de concepts, parcours, authentification, exemples et récupération d’erreurs qu’un schema seul ne peut expliquer. OpenAPI décrit très bien operations, paramètres, structures de request/response, status codes et schemas réutilisables.
Une approche pratique et vérifiable de « Des notes de version qui permettent réellement d’agir », conçue pour une documentation claire et maintenable. Comment traiter « Des notes de version qui permettent réellement d’agir » avec une approche pratique, vérifiable et maintenable de la documentation technique.