Diese Seite wurde von der Cloud Translation API übersetzt.

CNCF-Projekt (Cloud Native Computing Foundation)

Auf dieser Seite finden Sie die Details zu einem Projekt für technisches Schreiben, das für Google Season of Docs angenommen wurde.

Projektzusammenfassung

Open-Source-Organisation:: Cloud Native Computing Foundation (CNCF)
Technischer Redakteur:: Shriti
Projektname:: Verbesserte Dokumentation von SMI und zugehörigen Service Meshes
Projektlänge:: Standardlänge (3 Monate)

Projektbeschreibung

Die Service Mesh-Technologie soll vor allem die wachsende Anzahl von Diensten unterstützen, indem sie alle Sicherheits-, Verwaltungs- und Überwachungsanforderungen erfüllt. Das Service Mesh Interface (SMI) definiert eine Reihe von APIs für die häufigsten Service-Mesh-Anwendungsfälle (Trafficrichtlinie, Telemetrie und Verschiebung) und ermöglicht die Kompatibilität zwischen Service Meshes. Dies sind dedizierte Infrastrukturebenen für die Dienst-zu-Dienst-Kommunikation in einer Mikrodienstumgebung. Die Standardisierung dieser Schnittstellen wird die Nutzerfreundlichkeit verbessern und ist daher ein zukünftiges Ziel für SMI und zugehörige Service Meshes.

Aktueller Status:

Benutzerhandbücher: SMI ist ein relativ neues Sandbox-Projekt, das der CNCF im April 2020 gespendet wurde. Daher fehlt dem Projekt die Dokumentation für Endnutzer. Meshery ist eine Dienstverwaltungsebene mit Leistungs-Benchmarking für alle Arten von Diensten, die die Einführung, Konfiguration, Betrieb und Verwaltung der Leistung verschiedener Service Meshes erleichtern. Sie ermöglicht die Erfassung und Anzeige von Messwerten aus Anwendungen, die auf einem Service Mesh ausgeführt werden. Daher möchte ich mit einem Leitfaden für Meshery beginnen, der als Ausgangspunkt für die gesamte SMI-Nutzergemeinschaft dienen soll.

Nutzeranleitungen: Unter den bestehenden SMI-Plattformen: Die Beispielanwendung Learn Layer5 dient derzeit als Lerngerät für SMI und als Beispielanwendung für die Validierung der SMI-Spezifikationen.Ansonsten gibt es bei den SMI-Projekten überhaupt keine Tutorials für Endnutzer, was aufgrund der hochtechnischen Natur der Projekte ein erhebliches Hindernis darstellt. Meshery ist die perfekte Anwendung, um die Vorteile und die Nutzung von SMI und den zugehörigen Service Meshes zu demonstrieren. Deshalb werde ich es als Basistool verwenden, um die SMI-Funktionen zu präsentieren.

API-Dokumentation: Derzeit nicht verfügbar. SMI und verschiedene ähnliche Projekte haben ihre API-Endpunkte auf einer Plattform definiert. Beispielsweise sind die Endpunkte von Meshery unter server.go (https://github.com/layer5io/meshery/blob/master/router/server.go) definiert, aber sie sind weder gut kommentiert noch extern dokumentiert. Dies kann durch eine aussagekräftige Dokumentation der API behoben und durch Möglichkeiten für die Nutzer verbessert werden, die Endpunkte zu testen und eine Vorschau der Funktionen zu sehen.

Analyse:

Anleitungen für Nutzer sollen es den Nutzern ermöglichen, sich mit der Software vertraut zu machen und sie zu testen. Sie müssen interaktiv und ästhetisch ansprechend sein, um die Aufmerksamkeit der Nutzer zu wecken, und vor allem einfach zu bedienen.

Für das Erstellen oder Hosten von Anleitungen ist jedoch ein ausgefeilteres Format empfehlenswert, da Anleitungen oft als Nachschlagewerk dienen oder eine schnelle Lösung für Probleme bieten. Anstatt interaktiv zu sein, müssen sie gut strukturiert sein und sich auf Klarheit, Kohärenz und einen guten User Flow konzentrieren.

Eine mögliche Lösung hierfür wäre, separate Anleitungen für Nutzer mit Google Codelabs und eine unabhängige Anleitung mithilfe von Jekyll zu erstellen und sie schließlich in die API-Dokumentation einzubinden, um sowohl Endnutzern als auch zukünftigen Mitbearbeitern eine umfassende Erfahrung zu bieten.

Zielgruppe: SMI-Projekte bieten Bereitstellungs- und Betriebspraktiken, Lernumgebungen und Leistungsmesswerte für alle zugehörigen Projekte. Sie richtet sich sowohl an Einzelpersonen als auch an Organisationen.

Nutzerhandbücher: Ich richte mich an Anfänger, ohne dass ich davon ausgehe, dass sie bereits IT-Kenntnisse haben. Zielgruppe: Anfänger Begründung: Wird hauptsächlich als umfangreicher Referenzleitfaden verwendet, der im Laufe der Zeit aktualisiert werden muss. Dazu gehören ausführliche Erläuterungen und hilfreiche Tipps, damit Nutzer alle Informationen haben, die sie zum Einrichten und Arbeiten mit einem Service Mesh benötigen. Der Leitfaden wird ansprechender und nutzerfreundlicher, indem Videos, Bilder, Screenshots und GIFs hinzugefügt werden, wo es erforderlich ist.

Anleitungen für Nutzer: Zielgruppe: Anfänger Begründung: Der Schwerpunkt liegt darauf, die Anleitungen ansprechend und ästhetisch ansprechend zu gestalten, um die Aufmerksamkeit der Nutzer zu wecken und einen reibungslosen Testlauf der Software zu ermöglichen, was zu einem besseren Verständnis der Service Mesh-Benutzeroberfläche führt.

Dokumentation zum API-Endpunkt: Zielgruppe: Fortgeschrittene Nutzer Begründung: In diesem Abschnitt geht es um die Verwendung der komplexeren Funktionen der Service Mesh, was eher für fortgeschrittene Nutzer mit grundlegendem IT-Wissen interessant ist. Fortgeschrittene Nutzer suchen nach prägnanten Anleitungen, die bei Bedarf auch als Nachschlagewerke verwendet werden können. Die Endpunktdokumentation sollte so geschrieben werden, dass sie problemlos aktualisiert werden kann, ohne dabei ihre Genauigkeit oder Konsistenz zu beeinträchtigen. Dies sollte vorzugsweise ein automatisierter Prozess sein.

Ressourcen: Anleitungen für Nutzer: Google Developers Codelab – Hiermit können interaktive und umfassende Anleitungen für Endnutzer erstellt werden. Vorteile: – Sie können Sandbox-Anleitungen erstellen. – Sie haben einen praktischen Ansatz. – wurde mit Google Docs geschrieben und unterstützt Markdown-Text. – Kann mit Google Analytics überwacht werden – Nutzerzugriffe lassen sich leicht beobachten. – Einfach zu verwenden. Sie erstellen ästhetisch ansprechende Anleitungen, mit denen Nutzer direkt mit der Software interagieren können, ohne direkt investieren zu müssen.

Google Codelabs können mit dem CLaaT-Projekt (Codelabs as a Thing) erweitert und einfach bereitgestellt werden. Dieses Programm bietet ein Befehlszeilentool, mit dem Tutorials, die in Google Docs mit Markdown geschrieben wurden, in das Codelabs-Format (HTML) konvertiert werden können.

Nutzerhandbücher: Jekyll – Die vorhandene Dokumentation für meshery.io, die hier zu finden ist, wird auf Jekyll gehostet und verwendet das Docsy-Jekyll-Design. Es verwendet Markdown, Liquid, HTML und CSS, um fertig zum Hosten bereite, statische Websites zu erstellen, und wird in einer Ruby-Entwicklungsumgebung ausgeführt. Vorteile: – Websites können direkt aus GitHub-Repositories gehostet werden. – Ein gut unterstütztes Projekt mit einer sehr aktiven Community – Nutzerhandbücher und Erweiterungen können einfach in die bestehende SMI- und Meshery-Dokumentation aufgenommen werden, ohne dass Sie sich um die Migration auf eine andere Plattform kümmern müssen.

API-Dokumentation: Für die Erstellung der API-Dokumentation für SMI und Meshery wird Swagger (alternativ Swaggo) verwendet. Es ist eine elegante Lösung zum Erstellen von API-Dokumenten. Vorteile: - Dokumentation aus Ihrem API-Design: Sorgt dafür, dass Ihre Dokumentation bei der Weiterentwicklung Ihrer API auf dem neuesten Stand bleibt. – Dokumentation aus Ihrem API-Design: Kann automatisch aus API-Definitionen generiert werden. – Mehrere Dokumentationsversionen verwalten – Benutzerdefinierte API-Designs

Projektziele: – Mit Google Developer Codelabs interaktive Anleitungen für Endnutzer für SMI und zugehörige Service Meshes erstellen, wobei Meshery als Tool verwendet wird. – Endnutzerhandbuch mit Jekyll für Service Meshes erstellen - Verwenden Sie Swagger, um eine API-Endpunktdokumentation für SMI zu generieren. – Das Projekt sollte von der Community getragen werden, damit zukünftige und aktuelle Nutzer oder Entwickler es unter Anleitung und Moderation der SMI-Community ganz einfach weiter ausbauen können.

Zeitplan: Den vorgeschlagenen Zeitplan finden Sie hier: https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#bookmark=kix.j1b6m64eubsl

Struktur: Die vorgeschlagene Struktur für das Nutzerhandbuch finden Sie hier: https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing

Warum dieses Projekt? Die Service Mesh-Community wächst rasant, was durch die jüngste Integration als Sandbox-Projekt in die CNCF ermöglicht wurde. Das Projekt weist jedoch einen erheblichen Mangel an Dokumentation auf, sowohl für Endnutzer als auch für Entwickler. Ich habe in der Vergangenheit mit verschiedenen Servicemeshes experimentiert, darunter linkerD mit der EmojiVoto-App, Istio mit der Bookinfo-Anwendung und Consul von Hashicorp. Ich habe auch die SMI-Traffic-Aufteilung ausprobiert und verschiedene Validierungsregeln für meine Service Mesh-Konfiguration implementiert. Der Lernprozess ist faszinierend, aber sehr technisch und kann sowohl neue Nutzer als auch Entwickler abschrecken, die ihre ersten Schritte in die Service-Mesh-Community unternehmen oder Service Meshes für ihre eigenen persönlichen oder beruflichen Projekte verwenden möchten. Ich möchte diese Lücke schließen, was nur mit effizienten und gut dokumentierten Leitfäden und Anleitungen möglich ist.