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:
- Cloud Native Computing Foundation (CNCF)
- Rédacteur technique:
- Shrite
- Nom du projet:
- Améliorer la documentation sur les SMI et les maillages de services associés
- Durée du projet:
- Durée standard (3 mois)
Project description
La technologie de maillage de services a pour principal objectif d'apporter une valeur ajoutée au nombre croissant de services, en répondant à tous vos besoins en termes de sécurité, de gestion et de surveillance. L'interface de maillage de services (SMI, Service Mesh Interface) définit un ensemble d'API pour les cas d'utilisation les plus courants du maillage de services (règles de trafic, télémétrie et décalage) et permet la compatibilité entre les maillages de services, qui sont des couches d'infrastructure dédiées à la gestion de la communication de service à service dans un environnement de microservices. La standardisation de ces interfaces améliorera l'expérience de l'utilisateur final. C'est donc un objectif futur pour les SMI et les maillages de services associés.
État actuel:
Guides de l'utilisateur : SMI est un projet de bac à sable relativement nouveau, fait don à la CNCF en avril 2020. Par conséquent, le projet manque de documentation pour l'utilisateur final. Le maillage de services est un plan de gestion des services qui effectue une analyse comparative des performances de toutes sortes de services. Il facilite l'adoption, la configuration, l'exploitation et la gestion des performances des différents maillages de services. Il intègre la collecte et l'affichage des métriques des applications exécutées sur n'importe quel maillage de services. Je voudrais donc commencer par un guide pour Meshery qui servira de point de départ à toute la communauté d'utilisateurs SMI.
Tutoriels utilisateur : Parmi les plates-formes SMI existantes : L'application Learn Layer5 sert actuellement d'appareil d'apprentissage pour SMI et d'application pour effectuer la validation des spécifications SMI.Mais à part cela, les projets SMI sont complètement dépourvus de tutoriels pour utilisateurs finaux, ce qui constitue un obstacle sérieux en raison de la nature très technique des projets. Meshery est l'application idéale pour présenter les avantages et l'utilisation de la SMI et des maillages de services associés. C'est pourquoi je l'utiliserai comme outil de base pour présenter les fonctionnalités de SMI.
Documentation sur l'API : inexistante pour le moment. Les points de terminaison de l'API SMI et divers projets associés sont définis sur une plate-forme. Par exemple, les points de terminaison de Meshery sont définis sur server.go (https://github.com/layer5io/meshery/blob/master/router/server.go), mais ils ne sont ni bien commentés, ni documentés en externe. Pour résoudre ce problème, fournissez une documentation pertinente sur les API. Vous pouvez également l'améliorer en ajoutant des moyens permettant aux utilisateurs de tester ses points de terminaison et de prévisualiser ses fonctionnalités.
Analyse:
Les tutoriels utilisateur sont créés pour permettre à l'utilisateur de s'engager et de tester le logiciel. Ils doivent être interactifs et esthétiques afin de retenir l'attention de l'utilisateur et, surtout, faciles à utiliser.
Toutefois, pour rédiger ou héberger des guides de l'utilisateur, il est préférable d'utiliser un format plus mature, car ils servent souvent de guide de référence ou d'endroit où trouver une solution rapide en cas de problème. Plutôt que d'être interactifs, ils doivent être bien structurés et se concentrer sur l'amélioration de la clarté, de la cohérence et du bon flux utilisateur.
Une solution possible serait de créer des tutoriels utilisateur distincts à l'aide de Google Codelabs et d'un guide de l'utilisateur indépendant avec l'aide de Jekyll, puis de les intégrer à la documentation de l'API pour offrir une expérience complète à l'utilisateur final et aux futurs collaborateurs.
Audience cible : les projets SMI fournissent des pratiques de déploiement et opérationnelles, des environnements d'apprentissage et des analyses comparatives des performances pour tous les projets qui en dépendent. Il s'adresse aussi bien aux individus qu'aux organisations.
Guides utilisateur: je vais cibler les utilisateurs débutants, sans présumer de connaissances existantes en informatique. Cible: utilisateurs débutants Motif: Utilisé principalement comme guide de référence complet, qui devra être mis à jour au fil du temps. Vous y trouverez des explications détaillées et des conseils utiles pour vous assurer que l'utilisateur dispose de toutes les informations nécessaires pour configurer et utiliser un maillage de services. Nous allons rendre le Guide plus attrayant et plus convivial grâce à l'ajout de vidéos, de photos, de captures d'écran et de GIF si nécessaire.
Tutoriels utilisateur : Cible: Utilisateurs débutants Motif: Les tutoriels seront avant tout attrayants et esthétiques afin de retenir l'attention de l'utilisateur et de permettre un test fluide du logiciel, ce qui permettra de mieux comprendre l'interface du maillage de services.
Documentation sur le point de terminaison de l'API : Cible: Utilisateurs avancés Motif: Cette section se concentre sur l'utilisation des fonctionnalités les plus complexes du maillage de services, ce qui est plus dans l'intérêt des utilisateurs avancés qui possèdent des connaissances de base en informatique. Les utilisateurs avancés recherchent des tutoriels concis qui peuvent également servir de guides de référence, si nécessaire. La documentation sur les points de terminaison doit être écrite de manière à faciliter leur mise à jour sans compromettre sa précision ni sa cohérence. De préférence, un processus automatisé.
Ressources : Tutoriels pour les utilisateurs : Atelier de programmation Google Developers : permet de créer des tutoriels interactifs et complets pour les utilisateurs finaux. Avantages : - Peut produire des tutoriels de bac à sable. - Adopter une approche pratique. - Rédigé à l'aide de Google Docs et compatible avec le texte Markdown. - Ils peuvent être surveillés à l'aide de Google Analytics. Ils permettent d'observer facilement le trafic utilisateur. - Facile à utiliser. Elle produit des tutoriels esthétiques qui permettent à l'utilisateur d'interagir directement avec le logiciel sans aucun investissement direct.
Google Codelabs peut être amélioré et facilement déployé à l'aide du projet CLaaT (Codelabs as a Thing). Il s'agit d'un programme qui propose un outil de ligne de commande permettant de convertir les tutoriels écrits dans Google Docs à l'aide de Markdown au format HTML.
Guides de l'utilisateur : Jekyll : la documentation existante de Meshery.io, disponible ici, est hébergée sur Jekyll et utilise le thème Docsy Jekyll. Elle utilise Markdown, Liquid, HTML et CSS pour produire des sites Web statiques prêts à être hébergés, et s'exécute dans un environnement de développement Ruby. Avantages : - Peut héberger des sites directement à partir de dépôts GitHub. - Il s'agit d'un projet bien pris en charge, avec une communauté très active. - Il suffit d'ajouter des guides utilisateur et des améliorations à la documentation existante sur SMI et Meshery, sans avoir à vous soucier de la migration vers une autre plate-forme.
Documentation de l'API : Swagger (ou Swaggo) sera utilisé pour créer la documentation de l'API pour SMI et Meshery. C'est une solution élégante pour rédiger des documents d'API. Avantages : - Documentation issue de votre conception d'API: garantit que votre documentation reste à jour au fur et à mesure que votre API évolue. - Documentation de votre conception d'API: peut être généré automatiquement à partir des définitions d'API. - Gérer plusieurs versions de la documentation - Conceptions d'API personnalisées
Objectifs du projet : - Utiliser les ateliers de programmation Google Developers pour créer des tutoriels interactifs destinés aux utilisateurs finaux pour l'API SMI et les maillages de services associés en utilisant Meshery comme outil - Créer un guide de l'utilisateur final utilisant Jekyll pour le maillage de services - Générer de la documentation sur les points de terminaison de l'API pour SMI à l'aide de Swagger - Faites en sorte que le projet soit axé sur la communauté afin que les utilisateurs ou développeurs actuels et futurs puissent facilement continuer à l'enrichir sous les conseils et la modération de la communauté SMI.
Calendrier : Le calendrier proposé est disponible ici : https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#bookmark=kix.j1b6m64eubsl
Structure : La structure proposée pour le guide de l'utilisateur est disponible à l'adresse suivante : https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing
Pourquoi ce projet ? La communauté du maillage de services s'étend à un rythme effréné, grâce à son intégration récente en tant que projet de bac à sable à la CNCF. Cependant, le projet constate une grave pénurie de documentation, tant pour les utilisateurs finaux que pour les développeurs. J'ai déjà joué avec différents maillages de services, y compris linkerD avec l'application EmojiVoto, Istio avec son application Bookinfo et le service Consul de Hashicorp. J'ai également essayé la répartition du trafic SMI et j'ai appliqué différentes règles de validation à la configuration de mon maillage de services. Le processus d'apprentissage est fascinant, mais hautement technique. Il peut être rebutant pour les nouveaux utilisateurs ainsi que pour les développeurs, qui souhaitent faire leurs premiers pas dans la communauté du maillage de services ou les utiliser pour leurs projets personnels ou professionnels. J'aimerais combler cet écart, ce qui ne peut être fait qu'avec des guides et des tutoriels efficaces et bien documentés.