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:
- Passerelle-gRPC
- Rédacteur technique:
- iamrajiv
- Nom du projet:
- Refactoriser le site de documentation existant de gRPC-Gateway
- Durée du projet:
- Durée standard (3 mois)
Project description
EXTRAIT:
Le site de documents utilisateur est conçu pour aider les utilisateurs finaux à utiliser un produit ou un service. Un bon site de documentation pour les utilisateurs est très important, car il permet aux utilisateurs d'apprendre à utiliser le logiciel, de découvrir ses fonctionnalités, de bénéficier de conseils et d'astuces. Il permet également de résoudre les problèmes courants rencontrés lors de l'utilisation du logiciel. Elle réduit également les coûts d'assistance et fait partie de l'identité d'entreprise du produit. Un bon site de documentation pour les utilisateurs est un signe de l'intégrité du produit, l'équipe de développeurs. Sans un bon site de documentation utilisateur, un utilisateur peut ne pas savoir comment faire les choses ci-dessus de manière efficace. Le site docs pour les utilisateurs peut jouer un rôle essentiel dans le succès d'un produit, car une communication de qualité est et sera toujours au cœur de toute entreprise ou produit. Une documentation de qualité s'appuie simplement sur cette communication et la place dans un cadre gérable auquel tout le monde peut accéder pour réussir.
Au moment de la rédaction de cet article, le dépôt gRPC-Gateway a été dupliqué par environ 1 200 fois, et 184 personnes ont contribué à ce dépôt. Cela montre que de nombreuses personnes dans le monde utilisent gRPC-Gateway. Nous vous conseillons de consulter sa documentation utilisateur pour savoir comment utiliser gRPC-Gateway. Toutefois, le site de documentation et de documentation utilisateur de gRPC-Gateway est actuellement obsolète et incomplet, et la communauté gRPC-Gateway souhaite utiliser ce projet pour refactoriser le site de documentation existant afin d'améliorer son site de documentation afin de permettre aux utilisateurs finaux d'utiliser gRPC-Gateway.
ÉTAT ACTUEL:
Actuellement, le site de documentation gRPC-Gateway présente deux problèmes majeurs :
• Le premier problème est le problème d'un site Web Google Docs de mauvaise qualité et obsolète. Le style et la structure du site et le thème utilisé sont obsolètes, incomplets, difficiles à parcourir ou difficiles à trouver, ne couvrent pas de nombreuses fonctionnalités d'un bon site Web Google Docs. La refactorisation du site Docs existant de gRPC-Gateway comprendra le stylisation du site Web, l'ajout de fonctionnalités telles que la recherche de documents, l'amélioration de l'interface utilisateur du site Web, l'organisation des tutoriels et des exemples dans une barre latérale appropriée, et la mise à jour des organigrammes et des images existants en en créant un nouveau, etc. Ce sera mon objectif principal, et mon travail sera davantage basé sur le style et la restructuration du site Docs existant.
• Deuxième problème : il est nécessaire de refactoriser la documentation existante, les tutoriels, les exemples, etc. de gRPC-Gateway, ce qui peut être fait en supprimant les erreurs typographiques et grammaticales dans les fichiers, en alignant correctement les extraits Go et en refactorisant les extraits Go en fonction des formats Gofmt. Nous pouvons également ajouter de la documentation, des tutoriels et des exemples si nécessaire, ou réutiliser les fichiers existants après les avoir refactorisés. C'est mon objectif secondaire et je le pourrai après avoir atteint mon objectif principal, c'est-à-dire modifier le style et la restructuration d'un site Google Docs existant.
POURQUOI MON SITE PROPOSÉ EST-IL D'AMÉLIORATION PAR LE SITE ACTUEL ?
Le site Web proposé dans les documents pour les utilisateurs sera structuré de manière à améliorer et à garantir l'efficacité, la cohérence et la tranquillité d'esprit de l'utilisateur final. Elle offrira une interface et une apparence améliorées avec des sections bien stylisées et des fonctionnalités contenant des guides écrits, ainsi que les organigrammes et les images associés.
La documentation de gRPC-Gateway fournit une bonne description de la méthode et de l'exemple. Mais il utilise toujours l'ancien thème Jekyll et de nos jours, nous proposons de meilleurs thèmes Jekyll de SSG (Static Site Generator). Il est également nécessaire de restructurer les pages et de les rendre plus utiles pour les utilisateurs en ajoutant de nouveaux exemples et tutoriels, puis en mettant à jour et en réécrivant le contenu précédent.
STRUCTURE ET FEUILLE DE ROUTE DES OBJECTIFS ET IDÉES PROPOSÉS:
OBJECTIF PRINCIPAL DE CE PROJET:-
Vous pouvez mettre en œuvre les idées et objectifs ci-dessus de différentes manières :
Déplacement du thème Jekyll actuel vers un thème plus performant et plus performant. La raison d'utiliser à nouveau les thèmes Jekyll est qu'il sera facile pour les responsables de la maintenance de contribuer et de comprendre le flux de travail du projet, car ils connaissent déjà le framework et le thème Jekyll existants, qui sont similaires au nouveau thème Jekyll.
Après avoir parcouru différents thèmes Jekyll sur Internet, j'ai trouvé que cette https://idwhichbewriting.com/documentation-theme-jekyll/ suite de thèmes est idéale pour le site de documentation gRPC-Gateway en raison de la fonctionnalité suivante:
• Markdown:- Pour que les rédacteurs techniques n'aient pas à se soucier de l'installation. Ils peuvent écrire simplement dans le fichier .md. Tout le monde peut cliquer sur le bouton de modification affiché sur le site Web (nouvelle fonctionnalité) et contribuer (modifier/suggérer des modifications pour la page dans GitHub) pour l'améliorer. Cela incitera les utilisateurs à ajouter ou modifier du contenu afin de l'améliorer.
• Recherche de documentation:- L'utilisateur doit disposer d'un champ de recherche pour trouver facilement et rapidement les contenus pertinents.
• Section des commentaires:- L'utilisateur peut avoir la possibilité de commenter et de partager son point de vue sur les posts et les tutoriels. Ils peuvent lire les points de vue d'autres personnes sur la documentation du projet.
• Nouvelles notes de version et blogs:- Le site Web doit être mis à jour avec de nouveaux articles de blog et des actualités sur le développement actuel et la feuille de route. Le type de blog doit donc être présent sur la page de destination.
• Développement rapide : La plupart des frameworks de générateur de sites statiques s'exécutent sur le serveur, et les modifications apportées aux fichiers sont immédiatement répercutées dans l'interface utilisateur. Les processus de déploiement et de compilation devraient également être simples. À l'avenir, si nous voulons changer le cadre, nous utilisons. Alors ça devrait être facile. La plupart des frameworks sont compatibles avec l'écriture Markdown. Il suffit donc de déplacer les fichiers .md et de limiter les modifications.
Ici, je divise les pages existantes du site Web en nouvelles sections et pages de site Web :
• Page de destination :
La page de destination doit souligner les principales fonctionnalités de gRPC-Gateway.
- Premiers pas avec gRPC-Gateway (redirection vers le guide de l'utilisateur)
- Instructions d'installation simples (brèves commandes)
- Pourquoi utiliser gRPC-Gateway ?
- Projet utilisant gRPC-Gateway
L'idée de base est donc plutôt que de rédiger une longue description, d'afficher les points principaux sur la page de destination et de fournir un lien vers des informations détaillées.
• Page du guide de l'utilisateur gRPC-Gateway:-
- Guide d'installation
- Guide de démarrage rapide avec gRPC-Gateway
• Page du guide du développeur sur gRPC-Gateway:-
le guide de développement, le guide de contribution, la configuration de Git, le code de conduite, la configuration de la documentation, le workflow de développement, etc. renvoient vers des pages similaires. Il faut donc refactoriser et réorganiser tous les fichiers. La page de développement principale doit contenir toutes ces pages et le lien hypertexte sera créé à chaque étape.
• À propos de gRPC-Gateway Page :
La liste de tous les contributeurs doit être présente dans les sections relatives à l'équipe. Des liens rapides et des notes de version seront ajoutés, et les derniers blogs seront ajoutés pour inciter l'utilisateur à lire l'actualité de gRPC-Gateway.
• Blogs, notes de version et pages de tutoriels:-
Je pense que ce site Web devrait proposer une option pour les blogs. Les actualités et les communiqués peuvent ainsi être communiqués facilement. La page du tutoriel contient des discussions et des articles populaires qui clarifient les API et les concepts de gRPC-Gateway. Les contributeurs peuvent ajouter leurs liens de tutoriel sur la page du tutoriel.
Une fois la tâche ci-dessus terminée, mettez à jour les mêmes modifications dans la branche v2 et effectuez les mêmes modifications avec la branche principale de gRPC-Gateway.
OBJECTIF SECONDAIRE DE CE PROJET:-
D'autres modifications doivent être apportées pour rendre la documentation gRPC-Gateway plus robuste et plus lisible :
• Corriger les erreurs grammaticales et typographiques, et organiser et aligner les liens et les messages sur le site dans tous les fichiers existants de gRPC-Gateway
• Ajouter de la documentation et du contenu supplémentaires si nécessaire dans gRPC-Gateway, car la plupart des fonctionnalités ont une documentation très courte, comme dans la section Documentation du site sur AWS, Contexte et utilisation, etc.
• Refactorisation des extraits de code Go gRPC-Gateway selon les formats Gofmt
Une fois la tâche ci-dessus terminée, mettez à jour les mêmes modifications dans la branche v2 et effectuez les mêmes modifications avec la branche principale de gRPC-Gateway.
POURQUOI SUIS-JE LA BONNE PERSONNE POUR CE PROJET ?
Je pense être la bonne personne pour ce projet parce que :
• J'ai de l'expérience dans l'amélioration de la documentation des organisations et je peux utiliser n'importe quel système de contrôle des versions. L'exécution de commandes sur GitHub ne sera donc pas un problème. • De plus, ce qui me motive, c'est de travailler sur des projets qui créent de la valeur pour les gens. Je crois que si vous voulez que quelqu'un fasse quelque chose de la manière la plus efficace possible, vous le documentez. En documentant vos processus, vous garantissez l'efficacité, la cohérence et la tranquillité d'esprit de toutes les personnes concernées. • Je connais le workflow et le codebase de gRPC-Gateway, car j'y ai contribué depuis deux mois et j'ai fusionné 11 PR.