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:
- Cloud Native Computing Foundation (CNCF)
- Rédacteur technique:
- Shriti
- Nom du projet:
- Amélioration de la documentation sur les SMI et les réseaux de services associés
- Durée du projet:
- Durée standard (trois mois)
Project description
La technologie de maillage de services vise essentiellement à apporter de la valeur au nombre croissant de services, en gérant tous vos besoins en matière de sécurité, de gestion et de surveillance. L'interface Service Mesh (SMI) définit un ensemble d'API pour les cas d'utilisation les plus courants du maillage de services (règle de trafic, télémétrie et transfert) 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 utilisateur finale. Il s'agit donc d'un objectif futur pour les SMI et les réseaux de services associés.
État actuel:
Guides utilisateur : SMI est un projet de bac à sable relativement récent, donné au CNCF en avril 2020. Par conséquent, la documentation destinée aux utilisateurs finaux est insuffisante. Meshery est un plan de gestion de services avec des analyses comparatives des performances pour tous types de services, ce qui facilite l'adoption, la configuration, l'exploitation et la gestion des performances de différents réseaux de services. Il intègre la collecte et l'affichage des métriques des applications exécutées sur n'importe quel réseau de services. Je voudrais donc commencer par un guide sur Meshery, qui servira de point de départ à l'ensemble de la communauté des utilisateurs de SMI.
Tutoriels utilisateur : Parmi les plates-formes SMI existantes : L'exemple d'application, Learn Layer5, sert actuellement de dispositif d'apprentissage pour SMI et d'exemple d'application pour valider les spécifications SMI.Mais sinon, les projets SMI manquent complètement de tutoriels pour les utilisateurs finaux, ce qui constitue un obstacle majeur 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 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 de l'API : inexistante pour le moment. Les points de terminaison de l'API de SMI et de divers projets associés sont définis sur une plate-forme. Par exemple, les points de terminaison de Meshery sont définis dans 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. Ce problème peut être résolu grâce à une documentation pertinente des API et amélioré en ajoutant aux utilisateurs des moyens de tester ses points de terminaison et de prévisualiser ses fonctionnalités.
Analyse:
Les tutoriels utilisateur sont créés pour permettre à l'utilisateur d'interagir et de tester le logiciel. Elles doivent être interactives et esthétiques pour retenir l'attention des utilisateurs, et surtout faciles à utiliser.
Toutefois, pour rédiger ou héberger des guides utilisateur, un format plus mature est recommandé, car ils servent souvent de guide de référence ou de solution rapide aux problèmes. Plutôt que d'être interactives, elles doivent être bien structurées et axées sur l'amélioration de la clarté, de la cohérence et d'un bon parcours utilisateur.
Une solution possible serait de créer des tutoriels utilisateur distincts à l'aide de Google Codelabs et 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 d'exploitation, des environnements d'apprentissage et des benchmarks de performances à tous les projets qui en dépendent. Il s'adresse à la fois aux particuliers et aux organisations.
Guides utilisateur: je vais cibler les utilisateurs débutants, sans présumer de connaissances IT préalables de leur part. Cible: Utilisateurs débutants Motif: Utilisé principalement comme vaste guide de référence, qui devra être mis à jour au fil du temps. Il comprend des explications détaillées et des conseils utiles pour s'assurer que l'utilisateur dispose de toutes les informations dont il a besoin pour configurer et utiliser un service mesh. Nous allons rendre le Guide plus attrayant et plus convivial en y ajoutant des vidéos, des photos, des captures d'écran et des GIF, si nécessaire.
Tutoriels utilisateur : Cible: utilisateurs débutants Rationale: L'objectif est de rendre les tutoriels attrayants et esthétiquement agréables pour retenir l'attention de l'utilisateur et permettre un test fluide du logiciel, ce qui permettra de mieux comprendre l'interface de service mesh.
Documentation sur les points 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, qui sont davantage destinées aux utilisateurs avancés ayant 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 du point de terminaison doit être rédigée de manière à pouvoir être facilement mise à jour sans compromettre son exactitude ni sa cohérence. Il s'agit de préférence d'un processus automatisé.
Ressources : tutoriels utilisateur : 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. - A une approche pratique. - Rédigé à l'aide de Google Docs et compatible avec le texte Markdown. - Il peut être surveillé à l'aide de Google Analytics, un outil simple d'observation du trafic utilisateur. - Simplicité d'utilisation Crée des tutoriels esthétiques qui permettent à l'utilisateur d'interagir directement avec le logiciel sans investissement direct.
Les Google Codelabs peuvent être améliorés et déployés facilement à 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 codelabs (HTML).
Guides utilisateur : Jekyll : la documentation existante de meshery.io, disponible ici, est hébergée sur Jekyll et utilise le thème Docsy Jekyll. Il utilise Markdown, liquid, HTML et CSS pour produire des sites Web statiques prêts à être hébergés et s'exécute sur un environnement de développement Ruby. Avantages : - Vous pouvez héberger des sites directement à partir de dépôts GitHub. - Il s'agit d'un projet bien soutenu, avec une communauté très active. - Vous pouvez simplement ajouter des guides d'utilisation et des améliorations à la documentation existante sur SMI et Meshery, sans avoir à vous préoccuper de migrer 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. Il s'agit d'une solution élégante pour rédiger des documents d'API. Avantages : - Documentation issue de la conception de votre API: garantit que votre documentation reste à jour à mesure que votre API évolue. - Documentation de votre conception d'API: peut être générée automatiquement à partir des définitions d'API. - Gérer plusieurs versions de documentation - Concevoir des API personnalisées
Objectifs du projet : - Utiliser les ateliers de programmation Google pour les développeurs afin de créer des tutoriels interactifs pour les utilisateurs finaux sur les SMI et les réseaux de services associés à l'aide de Meshery comme outil. - Créez un guide pour les utilisateurs finaux, à l'aide de Jekyll pour les réseaux de services. - Utiliser Swagger pour générer la documentation sur les points de terminaison de l'API pour SMI - Faites en sorte que le projet soit géré par la communauté afin que les futurs et actuels utilisateurs ou développeurs puissent facilement continuer à l'enrichir sous la supervision et la modération de la communauté SMI.
Calendrier : consultez le calendrier proposé 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 ici : https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing
Pourquoi ce projet ? La communauté du service mesh se développe à une vitesse fulgurante, grâce à son intégration récente en tant que projet de bac à sable dans le CNCF. Cependant, le projet souffre d'un manque de documentation important, à la fois pour les utilisateurs finaux et les développeurs. J'ai déjà expérimenté différents réseaux de services, y compris linkerD avec l'application EmojiVoto, Istio avec son application bookinfo et Consul d'Hashicorp. J'ai également essayé la répartition du trafic SMI et implémenté diverses règles de validation sur la configuration de mon maillage de services. Le processus d'apprentissage est fascinant, mais très technique. Il peut rebuter les nouveaux utilisateurs et les développeurs qui souhaitent faire leurs premiers pas dans la communauté des réseaux de services ou les utiliser pour leurs propres projets personnels ou professionnels. Je voudrais combler ce fossé qui ne peut être accompli qu'avec des guides et des tutoriels efficaces et bien documentés.