Les tutoriels aident les utilisateurs à découvrir des produits et à résoudre des problèmes réels en les guidant tout au long du workflow associé à une tâche. Les tutoriels ont un ton plus conversationnel que les autres contenus. Un tutoriel s’apparente à une conversation entre deux développeurs, mais reste accessible aux lecteurs ayant des connaissances techniques variées. Les produits avec des tutoriels doivent déjà avoir un guide de démarrage rapide. Pour les petits workflows, utilisez plutôt le modèle de démarrage rapide.
Les tutoriels s’adressent aux personnes qui souhaitent obtenir des conseils d’experts et une discussion détaillée des bonnes pratiques liées à leur problème. Les tutoriels aident également les personnes ayant déjà implémenté des solutions similaires avec d’autres produits à passer à GitHub. Les tutoriels peuvent également aider les utilisateurs à vérifier si la solution est adaptée à leurs besoins.
Nous regroupons les tutoriels et guides de démarrage rapide sous l’appellation collective de « guides » sur le site. Dans les pages de destination /guides, nous incluons des tutoriels, des guides de démarrage rapide et certains articles procéduraux dans la liste des guides pour un ensemble de documents.
Comment écrire un tutoriel
Pour le modèle de didacticiels, consultez « Modèles ».
Contenu des tutoriels :
- Introduction
- Précise l’audience.
- Indique clairement les prérequis et les connaissances préalables nécessaires.
- Indique ce qu’une personne pourra accomplir ou générer.
- Inclut un exemple de projet réussi.
- N’indique pas la durée nécessaire pour effectuer la tâche, car cela dépend du niveau d’expérience de la personne suivant le tutoriel.
- Sections procédurales
- En fonction de l’audience du tutoriel, les étapes peuvent être moins explicites et formelles que celles précisées dans le contenu procédural. Vous n’avez pas besoin d’utiliser des éléments réutilisables existants pour former ces étapes si l’audience n’a pas besoin de ce niveau de détail.
- Utilisez : « À partir de votre profil, cliquez sur Paramètres, puis sur Paramètres du développeur ».
- Évitez : Dans le coin supérieur droit d’une page, cliquez sur la photo de votre profil, puis sur Paramètres. Dans la barre latérale gauche, cliquez sur Paramètres de développeur.
- Créez des liens vers d’autres articles ou ressources plutôt que de les reproduire, afin d’éviter d’interrompre le flux d’informations dans le tutoriel.
- Donnez des signaux visuels. Utilisez des blocs de code et des captures d’écran pour rassurer les utilisateurs sur le fait qu’ils effectuent les actions appropriées.
- Fournissez des exemples concrets.
- Par exemple, ne dites pas à quelqu’un d’entrer un message de commit. Donnez-lui plutôt un exemple de message de commit approprié qui correspond aux étapes précédentes.
- En fonction de l’audience du tutoriel, les étapes peuvent être moins explicites et formelles que celles précisées dans le contenu procédural. Vous n’avez pas besoin d’utiliser des éléments réutilisables existants pour former ces étapes si l’audience n’a pas besoin de ce niveau de détail.
- Dépannage
- Faites état des difficultés qui peuvent se présenter au cours de la tâche et listez quelques problèmes courants et les solutions correspondantes.
- Conclusion
- Passez en revue ce qui a été accompli ou créé. Faites référence au projet fourni dans l’introduction pour donner un exemple de projet réussi.
- Étapes suivantes
- Incluez 2 à 3 étapes actionnables qu’un utilisateur peut entreprendre une fois le tutoriel terminé. Créez un lien vers d’autres informations connexes, par exemple :
- Projets sur GitHub qui illustrent les concepts introduits
- Informations pertinentes sur docs.github.com
- Formations GitHub Skills pertinentes
- Discussions, billets de blog ou billets postés dans le forum Community par Hubbers
- Incluez 2 à 3 étapes actionnables qu’un utilisateur peut entreprendre une fois le tutoriel terminé. Créez un lien vers d’autres informations connexes, par exemple :
Instructions relatives aux titres pour les tutoriels
- Suivez les instructions relatives aux titres pour les articles procéduraux.
- N’utilisez pas « tutoriel » ou « guide » dans le titre.
Exemples de tutoriels
Tutoriels :
- Ajout d’étiquettes à des problèmes
- Installation d’un certificat Apple sur des exécuteurs macOS pour le développement Xcode
Guides de langage et de framework :