Phase actuelle:
Le programme Season of Docs 2021 s'est terminé le 14 décembre 2021. Voir la chronologie.
Voici quelques conseils pour aider les organisations Open Source à travailler efficacement avec des rédacteurs techniques.
Présentez-lui le monde de l'open source et votre communauté.
- Faites une "visite guidée" de votre communauté au rédacteur technique. Où peuvent-ils poser des questions ? À quelles réunions régulières doit-il participer ou à quelles listes de diffusion doit-il s'abonner ? De quels comptes ont-ils besoin (Github, Discord, Slack) ? Assurez-vous qu'ils comprennent le code de conduite de votre projet et qu'ils savent comment signaler les problèmes. Assurez-vous que votre rédacteur technique a compris la licence de votre projet et qu'il respecte toutes les exigences des autres employeurs concernant la signature d'accords de licence pour les contributeurs, des APD ou d'autres accords.
- Si possible, présentez-lui quelques personnes situées dans des fuseaux horaires qui se chevauchent et qui peuvent répondre rapidement à ses questions sur la communauté ou le projet.
- Si possible, envoyez-lui des goodies du projet.
Aidez le rédacteur technique à utiliser les outils et les processus nécessaires pour contribuer à votre projet.
- Si vos processus ne sont pas bien documentés, prévoyez un rendez-vous pour présenter au rédacteur technique sa première contribution, son premier problème ou sa première demande de tirage. Quels modèles ou balises doit-il utiliser ? Qui doit examiner sa contribution, et comment et quand doit-il donner suite aux commentaires ? Si son travail inclut des exemples de code, comment les tester ? Que doit-il savoir sur votre processus ou vos versions CI/CD ?
Aidez le rédacteur technique à comprendre votre projet et ses utilisateurs
- Expliquez votre projet en détail afin que le rédacteur technique acquière une compréhension conceptuelle solide du produit. Cela peut aider le rédacteur technique à se sentir plus confiant et à être plus autoritaire dans son écriture pour le projet.
- Décrivez les besoins des personnes qui utilisent le projet. Soyez aussi précis que possible : pas seulement "développeurs", mais aussi "développeurs créant des sites Web" et "développeurs qui programment des robots industriels".
- Mettez le rédacteur technique en relation avec les experts nécessaires. En d'autres termes, les développeurs ou autres contributeurs du projet responsables des aspects de votre projet que la documentation couvrira.
- Assurez-vous que le rédacteur technique dispose du temps et des ressources dont il a besoin de la part des experts du sujet et des autres membres de la communauté.
Posez des questions !
- Votre communauté ou votre projet n'ont peut-être jamais travaillé avec des rédacteurs techniques ou des contributeurs à la documentation auparavant. Profitez de cette occasion pour apprendre tout en partageant vos connaissances. Demandez des commentaires sur vos processus et vos outils. Votre rédacteur technique aura probablement quelques suggestions d'amélioration.