Ce guide fournit des instructions sur la rédaction de documentation efficace de type “comment faire” pour Discourse. Il couvre les éléments essentiels tels que la structure et le style, la considération du public cible, et la maintenance.
Niveau d’utilisateur requis : Tout le monde peut rédiger de nouveaux guides “comment faire”
Rédiger une documentation efficace de type “comment faire” est crucial pour aider les utilisateurs, les modérateurs, les administrateurs et les administrateurs système à effectuer diverses tâches au sein de Discourse. Ce guide vous aidera à créer des guides clairs et précieux pour la communauté.
Résumé
Dans cette documentation, vous apprendrez :
- Pourquoi rédiger un guide “comment faire” est important
- Quelles informations doivent être incluses
- Des directives pour la structure et le style
- Où publier ces sujets
- Comment les maintenir après la publication
Pourquoi rédiger un guide “comment faire” ?
Avez-vous déjà eu besoin d’effectuer une tâche et n’avez-vous pas pu vous rappeler comment la faire ? Rédiger un document de type “comment faire” est un excellent moyen de documenter les processus dans Discourse. Si vous rencontrez des difficultés avec un processus particulier, il y a de fortes chances que quelqu’un d’autre aussi. Le documenter aide tout le monde.
En savoir plus sur ce qui différencie un guide “comment faire” d’autres types de documentation comme les tutoriels ou les guides de référence dans ce guide de Divio.
Rédiger ou réviser un guide “comment faire” est un excellent moyen de commencer à contribuer vos connaissances de Discourse à la communauté. Pour d’autres façons de contribuer, consultez le guide sur comment contribuer à Discourse.
Quelles informations doivent être incluses ?
Un guide “comment faire” doit être un guide étape par étape menant l’utilisateur à un résultat spécifique. Par exemple, un guide intitulé “Configuration de HTTPS pour Discourse” doit fournir des instructions pour configurer HTTPS.
Points clés à retenir lors de la rédaction d’un guide “comment faire” :
- Restez sur le sujet et soyez clair
- Évitez les informations inutiles
- Soyez concis tout en étant informatif
- Expliquez pourquoi atteindre le résultat final est bénéfique
Tenez compte de votre public cible
Il existe différents publics pour les guides “comment faire” de Discourse, chacun nécessitant un niveau de détail différent. Utilisez les catégories de documentation comme guide pour déterminer à qui cibler votre guide :
- Documentation > Using Discourse
- Documentation > Site Management
- Documentation > Integrations
- Documentation > Hosted Customers
- Documentation > Self-Hosting
- Documentation > Migrating to Discourse
- Documentation > Developer Guides
- Documentation > Contributing
Comprenez le niveau de compétence technique de votre public et adaptez votre guide en conséquence. Quelques conseils :
- Évitez les étapes que le public ne peut pas effectuer (par exemple, les clients hébergés n’ont généralement pas accès aux commandes de console)
- Gardez les instructions claires et évitez un langage très technique pour les utilisateurs non techniques
- N’ajoutez pas d’informations de base que votre public devrait déjà connaître
Structure et style
Le guide de style de documentation couvre tout ce que vous devez savoir sur la manière de structurer et de styliser les guides “comment faire” (et toute autre documentation Discourse) :
Publication d’un guide
Publiez les guides dans une sous-catégorie de la catégorie parente Documentation et étiquetez-les avec how-to. Tous les guides nécessitent l’approbation de l’équipe Discourse, qui sera gérée automatiquement via le processus de modération. Le guide de style décrit chaque catégorie plus en détail pour vous aider à décider où votre guide doit être publié.
Maintenance de votre guide
Une fois que vous avez publié un guide “comment faire”, gardez-le à jour. Voici comment vous pouvez aider à le maintenir :
- Surveillez les réponses — Intégrez les commentaires de la communauté dans le guide.
- Testez le guide vous-même — Parcourez le guide périodiquement pour vous assurer qu’il est toujours précis.
- Corrigez les informations manquantes ou incorrectes — Si vous êtes au niveau de confiance 2 ou supérieur, modifiez le premier message du guide “comment faire”.
- Signalez les sujets pour obtenir de l’aide — Si vous ne pouvez pas effectuer de modification, signalez le message avec “Autre chose” et expliquez ce qui est nécessaire.
Dans la plupart des cas, les commentaires sur les guides officiels “comment faire” seront supprimés après un mois pour garder l’accent sur le guide lui-même.
Merci d’améliorer la documentation de la communauté Discourse ! Si vous êtes bloqué, n’hésitez pas à demander de l’aide. La meilleure façon de commencer est de contribuer et d’apprendre au fur et à mesure.