Cette page contient les détails d'un projet de rédaction technique accepté pour la Google Season of Docs.
Résumé du projet
- Organisation Open Source:
- GenPipes
- Rédacteur technique:
- shaloo
- Nom du projet:
- Configurer la documentation GenPipes sur Read The Docs
- Durée du projet:
- Durée standard (trois mois)
Project description
Je propose un plan en trois étapes pour atteindre l'objectif de configurer la documentation GenPipes sur Read The Docs.
Étape 1: PoC
Consulter la documentation existante sur GenPipes en tant que nouvel utilisateur / chercheur
- Identifier les informations manquantes et les inexactitudes
- suggérer de nouveaux sujets de document (le cas échéant) ;
- Ébauche de carte de l'architecture de l'information pour répondre à l'audience cible, en mettant l'accent sur les nouveaux utilisateurs.
(Remarque: Au cours de cette étape, nous pouvons également avoir besoin d'informations de la part des mentors GenPipes concernant la configuration d'un nouveau dépôt GitHub où les documents GenPipes pour RTD peuvent être hébergés. Ce dépôt GitHub peut être utilisé pour importer tous les documents dans les pipelines de compilation RTD. Pour cela, vous devrez peut-être obtenir des informations sur les règles du dépôt GenPipes et les consignes de gestion des sources de documents, le cas échéant. Sinon, vous pouvez en utiliser des standards. Pour la preuve de concept, je peux également vous montrer un exemple de configuration de dépôt RTD à l'aide de mon compte GitHub (par exemple, https://gpdocs.readthedocs.io/en/latest/, que j'ai créé pour cette proposition).
Sur la base de l'examen et de l'analyse effectués à l'étape précédente, créez un squelette de base de la structure / index de la documentation GenPipes proposée et publiez-le sur le site RTD.
- Cela implique la création d'un dépôt GitHub (avec des outils Sphinx, par exemple) et de fichiers de documentation de base.
- Cela implique également une nouvelle création de la table des matières qui tient compte à la fois des nouveaux utilisateurs et des usages chevronnés des différentes sections / flux d'informations.
Examiner / obtenir l'approbation de la table des matières de base
Lors de la phase d'évaluation de la GSoD GenPipes, j'ai essayé de créer de la valeur pour GenPipes via cet exemple hébergé sur RTD. Veuillez noter que cette information est fournie à des fins de démonstration uniquement. Elle est un lien protégé qui n'est pas encore accessible publiquement sur RTD. Que je sois sélectionné ou non, cette démonstration peut être utilisée pour lancer l'effort de recherche et développement de GenPipes. J'ai déjà vérifié les sources dans le dépôt GitHub c3g/GenPipes. Les mentors, Rola et Hector, l'ont appréciée précédemment lors de la discussion sur le partage d'écran sur Skype. J'ai donc pensé que GSoD Gods voudrait peut-être la voir aussi. Il s'agit d'un squelette basique pour le moment, mais je prévois de le mettre à jour si le temps me le permet d'ici le 30 juillet.
https://genpipes.readthedocs.io/en/latest/
Étape 2: Création du docset GenPipes Doc v0.9
Identifiez les documents GenPipes actuels ou existants qui peuvent être importés, liés ou convertis en documents basés sur Sphinx/rst pour héberger les données RTD en gardant à l'esprit les délais du GSoD.
Convertissez les documents identifiés au format rst, si nécessaire, créez-en de nouveaux le cas échéant et réutilisez tout ce qui est possible et pertinent.
- Importez cet ensemble de documents initial dans ReadTheDocs en tant que démonstration de faisabilité et hébergez-le dans un dépôt protégé. Ajoutez une note à l'avance pour suggérer aux nouveaux utilisateurs de consulter la documentation d'origine de GenPipes jusqu'à ce que l'examen/le changement officiel ait été donné.
Réviser/corriger/mettre à jour
Étape 3: Affiner, examiner et publier la première ébauche à la RTD
Renseignez les détails de la nouvelle structure de document GenPipes proposée dans la table des matières GenPipes. Ajoutez d'autres documents en plus des premiers (fichier Readme de GenPipes), concepts, tutoriels, etc.
Ajoutez une démarcation claire dans la table des matières pour les nouveaux utilisateurs, les utilisateurs expérimentés de GenPipes, les développeurs GenPipes, etc.
Suggérez et discutez d'un processus de travail avec une automatisation partielle via RTD (builds Sphinx) sur la façon dont le set de documents GenPipes peut être géré et modifié par les utilisateurs, et si C3G le permettra pour les contributeurs externes aux documents. Il peut être nécessaire de créer des consignes pour les mises à jour de documents, comme pour les consignes de codage. Des sous-étapes supplémentaires peuvent être nécessaires. Par exemple, automatisez la vérification orthographique avant l'approbation des demandes de publication dans les documents GenPipes.
Signaler
Enfin, créez un rapport pour le GSoD en vous basant sur vos expériences, vos journaux et les commentaires de vos mentors.
Autres réflexions
À l'avenir (au-delà de trois mois), si nécessaire, je pourrai vous aider à gérer GenPipes sur le long terme. ou former d'autres personnes à faire de même, si nécessaire. Nous pourrons le déterminer en fonction des résultats de ces trois premiers mois.
De plus, je suggère une autre idée de proposition de projet : la création d'un résumé de trois pages GenPipes qui facilite l'intégration. Aujourd'hui, un nouvel utilisateur doit passer par de nombreuses étapes avant de pouvoir commencer à utiliser GenPipes, car la documentation est bonne, mais dispersée et pas adaptée aux nouveaux utilisateurs. Je ne suis pas sûr que cela puisse être fait en trois mois, mais je vais essayer.
La même proposition et son origine (historique) peuvent également être consultés à l'adresse https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing