Phase actuelle:
Le programme Season of Docs 2019 s'est terminé le 6 mars 2020. Consultez la chronologie.
Cette page contient des consignes destinées aux rédacteurs techniques sur la création de votre rapport de projet une fois que vous avez terminé votre travail pour la saison des documents de cette année.
L’envoi de votre rapport de projet
À l'ouverture de la phase de finalisation du projet, vous pouvez envoyer votre rapport de projet en remplissant un formulaire qui devient disponible dans la section Finalisation du projet du guide du rédacteur technique.
Informations à inclure dans le rapport du projet
Cette section décrit le type d'informations que vous pouvez fournir dans le rapport de votre projet. Le formulaire de rapport de projet comprendra des champs de texte libre ainsi que des questions à choix multiples.
Lien vers votre lieu de travail
Fournissez un lien renvoyant vers une description du travail que vous avez effectué.
Le lien doit renvoyer vers un document qui contient une brève description du travail effectué, la documentation que le projet Open Source a fusionnée dans son dépôt, un résumé de l'état actuel du projet, ainsi qu'une liste des défis et des apprentissages.
Le lien s'affichera dans les résultats "Saisonnier des documents" publiés sur le site Web. Les résultats publiés illustrent le travail que vous avez effectué pendant le programme. Les résultats publiés sont également un excellent moyen pour vous de vous référer à votre travail dans le cadre de votre CV.
Vous devez partager votre lien avec votre mentor et demander un examen avant de soumettre le rapport de votre projet.
Exigences pour votre rapport de projet
Tenez compte des exigences suivantes:
- Le contenu lié doit faciliter l'identification du travail que vous avez effectué pendant Season of Docs, c'est-à-dire les modifications que vous avez apportées ou la nouvelle documentation que vous avez rédigée.
- Le travail doit se trouver dans un endroit stable. Une fois l'envoi terminé, vous ne pourrez plus modifier l'URL.
Quelqu'un d'autre doit pouvoir utiliser le contenu disponible sur la cible du lien (ou référencé) pour s'appuyer sur votre travail.
- Si votre travail est terminé à 100 %, d'autres personnes doivent pouvoir l'utiliser.
- Si votre travail n'est pas terminé à 100 %, vous devez indiquer clairement ce qu'il vous reste à faire.
Bons exemples de la façon de décrire votre travail
Vous n'avez pas besoin d'effectuer toutes ces opérations, mais voici quelques méthodes pour y répondre:
Créez un article de blog, une page Web ou un Gist GitHub public qui décrit le travail que vous avez effectué et renvoie vers les commits que vous avez effectués et les dépôts sur lesquels vous avez travaillé. S'il reste du travail à effectuer sur le projet, incluez une description de ce travail. Vous pouvez également partager des temps forts ou des défis.
C'est la meilleure option, car elle vous permet d'inclure facilement de nombreuses informations. C'est bien, car cela montre clairement le travail que vous avez fait et permet aux autres d'utiliser et de comprendre facilement votre contribution.
Si vous utilisez GitHub et que l'ensemble de votre travail est couvert par une seule demande d'extraction, vous pouvez utiliser ce lien.
- Assurez-vous que la description de la demande d'extraction est détaillée.
- Assurez-vous que la description indique clairement que le travail est pour Season of Docs.
- Si la demande d'extraction nécessite plus de travail après la fin de Season of Docs, veillez à ce que la dernière saison de Docs en note l'entrée.
- Cette méthode de fourniture d'un rapport de projet présente l'avantage de regrouper le journal des modifications, la liste des commits et les commentaires des avis au même endroit.
Si votre dépôt GitHub a une seule fonction pour Season of Docs, ajoutez un fichier README contenant les détails de votre travail.
Créez un dossier public dans Google Drive et incluez tous les correctifs que vous avez créés.
Créez une feuille de calcul publique avec Google Sheets et répertoriez tous vos commits.
Ajoutez un lien vers un seul problème dans un Issue Tracker public, qui contient des références claires à votre travail et tout autre élément approprié. Le problème devrait suivre tout le travail que vous avez effectué. Assurez-vous que le problème répertorie tous les commits ou qu'il est facile de les trouver d'une autre manière.
Créez un lien vers une comparaison unifiée ou contextuelle de vos modifications. Veillez à inclure un en-tête incluant le nom de votre projet de rédaction technique et votre identité, afin qu'il soit utile aux autres utilisateurs.
De mauvais exemples de la façon de décrire votre travail
À éviter:
- Lien vers un fichier tarball ou ZIP contenant le code source de l'ensemble du projet ou votre répertoire de travail.
- Lien vers la partie supérieure du dépôt source principal du projet. Par exemple, si vous travaillez sur cpython, ce lien n'est pas utile : https://github.com/python/cpython.
- Lien vers votre clone du dépôt source du projet. Il est donc difficile de voir quelles modifications sont apportées, car votre travail est mélangé à celui d'autres personnes.
- Lien vers la description de votre projet sur le site Web Season of Docs.
Pour les mentors
Veuillez aider votre rédacteur technique à créer un rapport de projet approprié. Il est important de procéder ainsi avant de créer votre propre évaluation du travail du rédacteur technique.
Vérifiez les éléments suivants :
- L'envoi doit respecter les exigences décrites ci-dessus.
- La soumission doit inclure une description du travail effectué, les exigences satisfaites et les motifs de toute décision spécifique prise.
L'idée de Season of Docs n'est pas que les rédacteurs techniques ne perdent pas beaucoup de documentation. Il est important que le travail puisse être utile au projet Open Source d'hébergement.