Projet GenPipes

Cette page contient les détails d'un projet de rédaction technique accepté pour Google Season of Docs.

Résumé du projet

Organisation Open Source:
GenPipes
Rédacteur technique:
shaloo
Nom du projet:
Configurer les documents GenPipes dans "Read The Docs"
Durée du projet:
Durée standard (3 mois)

Project description

Je propose un plan en trois étapes pour atteindre l'objectif de mise en place de la documentation GenPipes sur "Read The Docs".

Étape 1: démonstration de faisabilité

  • Consulter la documentation existante de GenPipes en tant que nouvel utilisateur / chercheur

    • Identifier les informations manquantes et les inexactitudes
    • Suggérer de nouveaux sujets de document (si nécessaire)
    • Brouillon de carte de l'architecture des informations pour s'adresser au public cible, en se concentrant sur les nouveaux utilisateurs.

    (Remarque: au cours de cette étape, nous aurons peut-être aussi besoin des commentaires des mentors GenPipes concernant la nouvelle configuration du dépôt GitHub dans laquelle les documents Genpipes pour le RTD peuvent être hébergés. Ce dépôt GitHub permet d'importer tous les documents dans les pipelines de compilation RTD. Cela peut nécessiter des insights sur les règles de dépôt GenPipes et des consignes de gestion des sources de documents, le cas échéant. Sinon, des méthodes standard peuvent être utilisées, afaik. Concernant la démonstration de faisabilité, je peux faire une démonstration d'un exemple de configuration d'un dépôt de RDT avec mon compte GitHub ; par exemple, https://gpdocs.readthedocs.io/en/latest/ - il s'agit d'un échantillon que j'ai créé pour cette proposition)

  • Sur la base de l'examen et de l'analyse de l'étape précédente, créez un squelette simple de la structure / index de la documentation GenPipes proposée et affichez-le sur le site RTD.

    • Cela implique la création d'un dépôt GitHub (avec les outils Sphinx, par exemple) et des fichiers de documentation de base.
    • Cela implique également la création d'une nouvelle table des matières pour tenir compte à la fois des nouveaux utilisateurs et des utilisateurs chevronnés pour différentes sections / flux d'informations.

  • Examiner / obtenir l'approbation de la table des matières du squelette de barebone

    Au cours de la phase d'évaluation du GSoD de GenPipes, j'ai essayé de créer de la valeur pour GenPipes à l'aide de cet exemple hébergé lors de la phase RTD. Veuillez noter que ce lien n'est utilisé qu'à des fins de démonstration. Il ne figure pas encore dans la liste publique des résultats de recherche. Que je sois sélectionné ou non, cette démonstration peut être utilisée pour lancer des projets de développement de l'activité sur GenPipes. J'ai déjà consulté les sources dans le dépôt GitHub c3g/GenPipes. Les mentors, Rola et Hector, l'ont apprécié lors de la discussion de partage de l'écran précédente sur Skype, et j'ai donc pensé que GSoD Gods voudrait aussi le voir. C'est un squelette pour l'instant, mais je prévois de le mettre à jour quand le temps le permettra, jusqu'au 30 juillet.

https://genpipes.readthedocs.io/en/latest/

Étape 2: Création d'un ensemble de documents GenPipes V0.9

  • Identifier les documents GenPipes actuels ou existants pouvant être importés, liés ou convertis en documentation basée sur Sphinx/rst pour l'hébergement sur RTD en tenant compte des chronologies GSoD

  • Convertissez les documents identifiés au premier format si nécessaire, créez-en d'autres le cas échéant et réutilisez tout ce qui est possible / pertinent.

    • Importez ce document initial défini dans ReadTheDocs comme démonstration de faisabilité et hébergez-le dans un dépôt protégé. Rédigez d'emblée une note pour suggérer aux nouveaux utilisateurs d'accéder à la documentation d'origine de GenPipes jusqu'à ce que l'examen ou la transition officielle soient autorisés.

  • Vérifier/Corriger le cours/Mettre à jour

Étape 3: Affinez, vérifiez et publiez la première ébauche lors du lancement prévu à cet effet

  • Remplissez les détails de la nouvelle structure de documents GenPipes proposée dans le TOC GenPipes. Ajoutez des documents supplémentaires en plus des premiers (Lisez-moi GenPipes), concepts, tutoriels, etc.

  • Ajouter une démarcation claire dans la table des matières pour s'adresser aux nouveaux utilisateurs, aux utilisateurs GenPipes chevronnés, aux développeurs GenPipes, etc.

  • Suggérer un processus de travail avec automatisation des parties via RTD (builds sphinx) sur la manière dont le jeu de documents GenPipes peut être géré et modifié par les utilisateurs, et si C3G autorise cela pour les contributeurs externes Cela peut nécessiter la création de consignes semblables aux directives de codage pour la mise à jour des documents. Peut nécessiter davantage de sous-étapes. Par exemple, automatisez le correcteur orthographique avant l'approbation du service public dans les documents GenPipes.

Rapport

Enfin, créez un rapport pour GSoD en fonction des expériences, des journaux et des commentaires des mentors.

Autres idées

À l'avenir (au-delà des trois mois), le cas échéant, je pourrai contribuer à maintenir cette fonctionnalité pour GenPipes à plus long terme. ou entraînez-en d'autres, si nécessaire. Nous pouvons le déterminer sur la base des résultats de ces trois premiers mois.

Je suggère également une idée de proposition de projet supplémentaire : la création d’un brief de page GenPipes 3 qui facilite l’intégration. Aujourd'hui, un nouvel utilisateur doit effectuer de nombreuses tâches avant de pouvoir commencer à utiliser GenPipes, car la documentation est bonne, mais dispersée et peu adaptée aux nouveaux utilisateurs. Je ne sais pas si cela peut être fait dans un délai de trois mois, mais j'aimerais essayer.

Vous pouvez également consulter cette proposition et son origine (historique) à l'adresse https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing