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:
- gRPC-Gateway
- Rédacteur technique:
- iamrajiv
- Nom du projet:
- Réfactorisation du site de documentation existant de gRPC-Gateway
- Durée du projet:
- Durée standard (trois mois)
Project description
RÉSUMÉ:
Le site de documentation utilisateur est conçu pour aider les utilisateurs finaux à utiliser un produit ou un service. Un site de documentation utilisateur de qualité est très important, car il permet aux utilisateurs d'apprendre à utiliser le logiciel, ses fonctionnalités, ses conseils et ses astuces, et de résoudre les problèmes courants rencontrés lors de son utilisation. Cela réduit également les coûts d'assistance et fait partie de l'identité de l'entreprise du produit. Un bon site de documentation pour les utilisateurs est le signe que le produit est sain, c'est-à-dire l'équipe de développeurs. Sans un site de documentation utilisateur de qualité, un utilisateur peut ne pas savoir comment effectuer les tâches ci-dessus de manière efficace. Un site de documentation utilisateur peut jouer un rôle essentiel dans la réussite d'un produit, car une bonne communication est et restera toujours au cœur de toute entreprise ou de tout produit. Une bonne documentation ne fait que mettre cette communication 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é créé environ 1 200 fois et 184 personnes y ont contribué. Cela montre que de nombreuses personnes dans le monde entier utilisent gRPC-Gateway et peuvent souhaiter lire sa documentation utilisateur pour savoir comment l'utiliser. Cependant, la documentation utilisateur et le site de documentation de gRPC-Gateway sont actuellement obsolètes et incomplets. La communauté gRPC-Gateway souhaite utiliser ce projet pour refactoriser le site de documentation existant et l'améliorer afin de permettre aux utilisateurs finaux de bénéficier d'une expérience fluide lorsqu'ils utilisent gRPC-Gateway.
ÉTAT ACTUEL:
Actuellement, le site de documentation de gRPC-Gateway présente deux problèmes majeurs :
• Le premier problème est que le site Web de documentation est mauvais et obsolète. Le style et la structure du site et du thème utilisés sont obsolètes, incomplets, difficiles à naviguer ou à trouver des informations, et ne couvrent pas de nombreuses fonctionnalités d'un bon site Web de documentation. La refactorisation du site de documentation existant de gRPC-Gateway comprendra la mise en forme 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, la mise à jour des organigrammes et des images existants en en concevant de nouveaux, etc. Ce sera mon objectif principal, et mon travail sera davantage axé sur la mise en forme et la restructuration du site de documentation existant.
• Le deuxième problème est la nécessité de refactoriser la documentation existante, les tutoriels et les exemples, etc. de gRPC-Gateway, ce qui peut être fait en supprimant les erreurs typographiques et grammaticales dans les fichiers, en effectuant l'alignement correct des extraits Go et en refactorisant ces extraits selon les formats Gofmt. Si c'est le cas, nous pouvons ajouter des documents, des tutoriels et des exemples supplémentaires si nécessaire, ou réutiliser les fichiers existants après avoir effectué la refactorisation. Il s'agit de mon objectif secondaire. Je l'atteindrai après avoir atteint mon objectif principal, à savoir la mise en forme et la restructuration du site Docs existant.
POURQUOI MON SITE DOCS PROPOSÉ EST-IL MEILLEUR QUE L'ACTUEL ?
Le site Web de documentation utilisateur proposé sera structuré pour améliorer et garantir l'efficacité, la cohérence et la tranquillité d'esprit des utilisateurs finaux. Elle améliore l'apparence et l'interface utilisateur grâce à des sections bien stylisées et des fonctionnalités contenant des guides écrits, ainsi que les diagrammes et les images associés.
La documentation de gRPC-Gateway fournit une bonne description de la méthode et de l'exemple. Cependant, il utilise toujours l'ancien thème Jekyll, alors que de nos jours, il existe de meilleurs thèmes Jekyll pour les générateurs de sites statiques (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, et en mettant à jour et en réécrivant les contenus précédents.
STRUCTURE ET FEUILLE DE ROUTE DES OBJECTIFS ET IDÉES PROPOSÉS:
OBJECTIF PRINCIPAL DE CE PROJET :
Les objectifs et idées ci-dessus peuvent être mis en œuvre de différentes manières :
Remplacement du thème Jekyll actuel par un thème plus performant et plus robuste. Le fait d'utiliser à nouveau des thèmes Jekyll permet aux mainteneurs de contribuer facilement au projet et de comprendre son workflow, car ils connaissent déjà le framework et le thème Jekyll existants, qui sont similaires au nouveau thème Jekyll.
Après avoir examiné différents thèmes Jekyll sur Internet, j'ai trouvé que la suite de thèmes https://idratherbewriting.com/documentation-theme-jekyll/ était la plus adaptée au site de documentation de 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 du contenu ou à modifier du contenu pour l'améliorer.
• Recherche de documentation : l'utilisateur doit disposer d'un champ de recherche pour pouvoir trouver facilement et rapidement les contenus pertinents.
• Section des commentaires : l'utilisateur peut avoir la possibilité de commenter et de partager son avis sur les posts et les tutoriels. Ils peuvent lire les points de vue des autres personnes sur la documentation du projet.
• Nouvelles notes de version et nouveaux blogs:- Le site Web doit être mis à jour avec de nouveaux articles de blog, ainsi que des informations sur le développement actuel et la feuille de route. Il faut donc que le blog soit présent sur la page de destination.
• Développement rapide : la plupart des frameworks SSG (Static Site Generator) s'exécutent sur le serveur, et les modifications apportées au fichier sont immédiatement répercutées dans l'UI. Le processus de déploiement et de compilation doit également être simple. À l'avenir, si nous voulons modifier le framework, nous utiliserons Ensuite, ça devrait être facile. La plupart des frameworks prennent en charge l'écriture Markdown. Il suffit donc de déplacer les fichiers .md et de quelques modifications.
Je vais diviser les pages existantes du site Web en nouvelles sections et pages :
• 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 (commandes courtes)
- Pourquoi utiliser gRPC-Gateway ?
- Projet utilisant gRPC-Gateway
L'idée de base est donc de ne pas rédiger de longue description, mais d'afficher les points principaux sur la page de destination et de fournir un lien pour en savoir plus.
• Page du guide de l'utilisateur de gRPC-Gateway :
- Guide d'installation.
- Guide de démarrage rapide avec gRPC-Gateway
• Page du guide du développeur gRPC-Gateway :
Le guide de développement, le guide de contribution, la configuration Git, le code de conduite, la configuration de la documentation, le workflow de développement, etc. pointent vers des pages similaires. Il est donc nécessaire de refactoriser et de réorganiser tous les fichiers. La page de développement principale doit contenir toutes ces pages, et le lien hypertexte sera créé à chaque étape.
• Page "À propos de gRPC-Gateway" :
La liste de tous les contributeurs doit figurer dans les sections de l'équipe. Liens rapides et notes de version. Les derniers blogs seront ajoutés pour inciter les utilisateurs à lire les actualités actuelles de gRPC-Gateway.
• Page des blogs, des notes de version et des tutoriels :
Je pense que le site Web doit proposer une option de blog. Il est ainsi possible de communiquer facilement les nouveautés et les communiqués. La page du tutoriel contient des conférences et des articles populaires qui clarifient les API et les concepts gRPC-Gateway. Les contributeurs peuvent ajouter leurs liens de tutoriel sur la page du tutoriel.
Une fois la tâche ci-dessus terminée, apportez les mêmes modifications dans la branche v2 et effectuez-les également dans 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
• Ajout de documentation et de contenu si nécessaire dans gRPC-Gateway, car la plupart des fonctionnalités sont accompagnées d'une documentation très courte, comme dans la section "Documentation" du site sur AWS, "Contexte" et "Utilisation", etc.
• Réfactorisation des extraits Go gRPC-Gateway conformément aux formats Gofmt
Une fois la tâche ci-dessus terminée, apportez les mêmes modifications dans la branche v2 et effectuez-les également dans la branche principale de gRPC-Gateway.
POURQUOI SUIS-JE LA BONNE PERSONNE POUR CE PROJET ?
Je pense être la personne idéale pour ce projet, car :
• J'ai déjà amélioré la documentation d'organisations et je peux utiliser n'importe quel système de contrôle de version. L'exécution de commandes sur GitHub ne sera donc pas un problème. • De plus, ce qui me motive 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 je contribue à gRPC-Gateway depuis deux mois et 11 PR ont été fusionnés.