Utilisez les sections de dépannage dans les guides ou articles procéduraux pour maintenir les solutions proches des procédures. Collaborez avec le support technique et les responsables des produits pour identifier les erreurs courantes et les inclure dans la documentation.
Problèmes connus
Les problèmes connus sont un sous-ensemble du contenu de dépannage qui est spécialement conçu pour répondre aux bogues, aux problèmes liés à l’expérience utilisateur et à l’interface utilisateur ainsi qu’à tout autre problème générant un volume élevé de tickets de support. Contrairement au contenu de dépannage qui décrit les erreurs que les utilisateurs peuvent rencontrer, les problèmes connus expliquent les problèmes que les utilisateurs vont rencontrer.
Comme tout contenu de dépannage, les problèmes connus peuvent constituer une section d’un article ou un article autonome. Si un problème connu s’applique à un article spécifique, documentez-le dans cet article. Si un problème connu s’applique à un ensemble spécifique d’articles ou à un regroupement conceptuel de fonctionnalités, ou si un produit ou une fonctionnalité présente plusieurs problèmes connus qui doivent être regroupés, créez un article dédié intitulé « Problèmes connus avec NOM ».
Le contenu des problèmes connus pour un produit ou une fonctionnalité n’a pas besoin d’être exhaustif. Contrairement à d’autres contenus de dépannage, certains problèmes connus peuvent ne pas avoir de solutions de contournement. La documentation d’un problème sans solution de contournement vise à aider les utilisateurs à confirmer l’existence du problème et à leur éviter de perdre du temps à rechercher une solution qui n’existe pas (GitHub ayant déjà déterminé l’absence de solution de contournement).
Les propriétaires de produits et de fonctionnalités (chefs de projet et directeurs techniques) doivent participer à la planification et à l’examen du contenu relatif aux problèmes connus.
Utilisez les problèmes connus pour expliquer les situations suivantes.
- Comportement du produit qui contredit régulièrement les attentes des utilisateurs, mais qui ne fait pas encore l’objet d’une procédure de correction.
- Comportement qui empêche régulièrement l’utilisation du produit ou de la fonctionnalité dans un but commun.
- Bogues rares ou graves pour lesquels GitHub n’a pas encore établi de procédure de correction et qui ne sont pas expliqués dans le produit ou dans le contenu existant sur GitHub Docs.
Comment écrire du contenu de dépannage ?
- Utilisez n’importe quel type de contenu GitHub Docs pour créer des sections de dépannage.
- Dans la mesure du possible, conservez le contenu de dépannage dans les contenus ou les guides procéduraux.
- Vous pouvez créer un article de dépannage séparé dans certains cas, par exemple si une rubrique particulière comprend du contenu de dépannage en grande quantité.
- Vous pouvez créer une thématique de dépannage si un produit ou une fonctionnalité compte de nombreux articles de dépannage, par exemple « Résolution des problèmes liés à SSH ».
Instructions relatives aux titres pour les contenus de dépannage
- Résolution des problèmes liés à FONCTIONNALITÉ
- Erreur : NOM DE L’ERREUR
- Problèmes connus concernant PRODUIT
Exemples de contenu de dépannage
- « Résolution des problèmes liés à SSH »
- « Utilisation de GitHub Enterprise Server avec un équilibreur de charge »
- « Problèmes connus » dans les notes de publication de GitHub Enterprise Server
- « Erreur : Nous effectuons un audit de clé SSH »