Diese Seite wurde von der Cloud Translation API übersetzt.

CNCF-Projekt (Cloud Native Computing Foundation)

Diese Seite enthält die Details zu einem Projekt für technisches Schreiben, das für die Google-Produktsaison von Google Docs akzeptiert wurde.

Projektzusammenfassung

Open-Source-Organisation:: Cloud Native Computing Foundation (CNCF)
Technischer Redakteur:: Shriti
Projektname:: Dokumentation von SMI und zugehörigen Service Meshes verbessern
Projektdauer:: Standarddauer (3 Monate)

Projektbeschreibung

Die Service Mesh-Technologie zielt im Wesentlichen darauf ab, der zunehmenden Anzahl von Diensten einen Mehrwert zu bieten, indem sie alle Sicherheits-, Verwaltungs- und Monitoringanforderungen erfüllt. Das Service Mesh Interface (SMI) definiert eine Reihe von APIs für die gängigsten Service Mesh-Anwendungsfälle (Traffic-Richtlinie, Telemetrie und Verschiebung) und ermöglicht die Kompatibilität zwischen Service Meshes. Das sind dedizierte Infrastrukturebenen für die Dienst-zu-Dienst-Kommunikation in einer Mikrodienst-Umgebung. Die Standardisierung dieser Schnittstellen sorgt für eine verbesserte Endnutzererfahrung und ist daher ein zukünftiges Ziel für SMI und zugehörige Service Meshes.

Aktueller Status:

Nutzerhandbücher: SMI ist ein relativ neues Sandbox-Projekt, das im April 2020 an CNCF gespendet wurde. Daher fehlt für das Projekt die Endanwendende-Dokumentation. Meshery ist eine Dienstverwaltungsebene mit Leistungs-Benchmarking für alle Arten von Diensten, die die Einführung, Konfiguration, den Betrieb und die Verwaltung der Leistung verschiedener Service Meshes erleichtert. Es umfasst die Sammlung und Anzeige von Messwerten aus Anwendungen, die auf einem beliebigen Service Mesh ausgeführt werden. Daher möchte ich mit einem Leitfaden für Meshery beginnen, der als Ausgangspunkt für die gesamte SMI-Nutzer-Community dienen soll.

Nutzeranleitungen: Unter den bestehenden SMI-Plattformen: Die Beispielanwendung Learn Layer5 dient derzeit als Lerngerät für SMI und als Beispielanwendung zur Validierung der SMI-Spezifikation.Ansonsten fehlen in den SMI-Projekten jedoch keine Anleitungen für Endnutzer, was aufgrund der hochtechnischen Natur der Projekte ein erhebliches Hindernis darstellt. Meshery ist die perfekte Anwendung, um die Vorteile und die Verwendung von SMI und den zugehörigen Service Meshes zu präsentieren. Deshalb werde ich sie als Basistool verwenden, um die Funktionen von SMI zu zeigen.

API-Dokumentation: Zurzeit nicht vorhanden. Die API-Endpunkte von SMI und verschiedenen ähnlichen Projekten werden auf einer Plattform definiert. Die Endpunkte von Meshery sind beispielsweise auf server.go definiert (https://github.com/layer5io/meshery/blob/master/router/server.go), aber sie sind weder extern kommentiert noch dokumentiert. Dieses Problem lässt sich mit einer aussagekräftigen Dokumentation der APIs beheben. Zur Optimierung können Nutzer außerdem Möglichkeiten zum Testen der Endpunkte und zum Testen der Funktionen hinzufügen.

Analyse:

Nutzeranleitungen werden erstellt, damit der Nutzer mit der Software interagieren und einen Testlauf durchführen kann. Sie müssen interaktiv und ästhetisch ansprechend sein, um die Aufmerksamkeit der Nutzenden aufrechtzuerhalten, und vor allem einfach zu bedienen.

Beim Schreiben oder Hosten von Benutzerhandbüchern ist jedoch ein ausgereifteres Format empfehlenswert, da Benutzerhandbücher häufig als Nachschlagewerk oder als Ort zur schnellen Lösung von Problemen dienen. Anstatt interaktiv zu sein, müssen sie gut strukturiert sein und sich auf die Verbesserung von Klarheit, Kohärenz und einem guten User Flow konzentrieren.

Eine mögliche Lösung wäre die Erstellung separater Nutzeranleitungen mithilfe von Google Codelabs und eines unabhängigen Benutzerhandbuchs mithilfe von Jekyll und deren Integration zusammen mit der API-Dokumentation, um sowohl dem Endnutzer als auch zukünftigen Mitbearbeitern ein umfassendes Erlebnis zu bieten.

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

Nutzerhandbücher: Ich richte mich an Einsteiger, ohne dass bereits IT-Kenntnisse auf Nutzerseite vorausgesetzt werden. Zielgruppe: Einsteiger Grund: Dient hauptsächlich als umfangreiches Referenzhandbuch, das mit der Zeit aktualisiert werden muss. Das umfasst detaillierte Erklärungen und hilfreiche Tipps, damit Nutzer alle Informationen haben, die sie zum Einrichten und Arbeiten mit einem Service Mesh benötigen. Die Übersicht wird durch das Hinzufügen von Videos, Bildern, Screenshots und GIFs bei Bedarf noch ansprechender und nutzerfreundlicher werden.

Nutzeranleitungen: Ziel: Einsteiger Grund: Der Schwerpunkt liegt darauf, die Anleitungen ansprechend und ästhetisch ansprechend zu gestalten, um die Aufmerksamkeit der Nutzer aufrechtzuerhalten und einen reibungslosen Testlauf der Software zu ermöglichen, was zu einem besseren Verständnis der Service Mesh-Oberfläche führt.

Dokumentation zu API-Endpunkten: Ziel: fortgeschrittene Nutzer Grund: In diesem Abschnitt geht es um die Verwendung der komplexeren Features des Service Mesh, die eher für fortgeschrittene Nutzer mit grundlegenden IT-Kenntnissen gedacht sind. Fortgeschrittene Nutzer suchen nach kurzen Tutorials, die bei Bedarf auch als Referenz verwendet werden können. Die Endpunktdokumentation sollte so geschrieben werden, dass eine Aktualisierung ohne Abstriche bei Genauigkeit oder Konsistenz möglich ist. Dies sollte vorzugsweise ein automatisierter Prozess sein.

Ressourcen: Nutzeranleitungen: Google Developers-Codelab: zur Erstellung interaktiver und umfassender Anleitungen für Endnutzer Vorteile: – Kann Sandbox-Anleitungen erstellen. - hat einen praktischen Ansatz. – Mit Google Docs erstellt und unterstützt Markdown-Text. - Kann mit Google Analytics überwacht werden - Leicht zu beobachtende Nutzerzugriffe - Einfach zu bedienen. Erstellt ästhetisch ansprechende Tutorials, die es den Nutzern ermöglichen, ohne Direktinvestitionen direkt mit der Software zu interagieren.

Google Codelabs können mit dem CLaaT-Projekt (Codelabs as a Thing) einfach erweitert und bereitgestellt werden. Dabei handelt es sich um ein Programm mit einem Befehlszeilentool, mit dem Anleitungen, die mit Markdown in Google Docs geschrieben wurden, in das Codelabs-Format (HTML) konvertiert werden können.

Nutzerhandbücher: Jekyll – Die vorhandene Dokumentation für Meshery.io, das Sie hier finden, wird auf Jekyll gehostet und verwendet das Docsy-Jekyll-Design. Sie verwendet Markdown, Liquid, HTML und CSS, um fertige statische Websites zu erstellen, und wird in einer Ruby-Entwicklungsumgebung ausgeführt. Vorteile: – Kann Websites direkt aus GitHub-Repositories hosten. - Dieses gut unterstützte Projekt mit einer sehr aktiven Community - Nutzerhandbücher und Verbesserungen können einfach in die bestehende SMI- und Meshery-Dokumentation aufgenommen werden, ohne dass eine Migration auf eine andere Plattform erforderlich ist.

API-Dokumentation: Swagger (alternativ Swaggo) wird zum Erstellen der API-Dokumentation für SMI und Meshery verwendet. Es ist eine elegante Lösung zum Schreiben von API-Dokumenten. Vorteile: – Dokumentation zum 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 - Individuelle API-Designs

Projektziele: - Mit Google Developer Codelabs interaktive Endnutzer-Tutorials für SMI und verwandte Service Meshes mit Meshery als Tool erstellen. - Erstellen eines Endnutzerhandbuchs mit Jekyll für Service Meshes – Mit Swagger eine API-Endpunktdokumentation für SMI generieren - die Projekt-Community voranbringen, damit zukünftige und aktuelle Nutzer oder Entwickelnde unter der Leitung und Moderation der SMI-Community problemlos weiter etwas hinzufügen 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? Dank der kürzlich erfolgten Integration als Sandbox-Projekt in CNCF wächst die Service Mesh-Community blitzschnell. Das Projekt verzeichnet jedoch einen erheblichen Mangel an Dokumentation, sowohl für Endnutzer als auch für Entwickelnde. Ich habe in der Vergangenheit mit verschiedenen Service Meshes gearbeitet, z. B. linkerD mit der App EmojiVoto, Istio mit der Anwendung „bookinfo“ und Consul von Hashicorp. Ich habe auch die Aufteilung des SMI-Traffics ausprobiert und verschiedene Validierungsregeln in meiner Service Mesh-Konfiguration implementiert. Der Lernprozess ist faszinierend, aber sehr technisch und kann sowohl für neue Nutzer als auch für Entwickler abschreckend sein, die ihre ersten Schritte in der Service Mesh-Community machen oder Service Meshes für ihre eigenen privaten oder beruflichen Projekte nutzen möchten. Ich möchte diese Lücke schließen, die nur mit effizienten und gut dokumentierten Leitfäden und Anleitungen möglich ist.