Ta strona została przetłumaczona przez Cloud Translation API.

projekt Cloud Native Computing Foundation (CNCF)

Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.

Podsumowanie projektu

Organizacja open source:: Cloud Native Computing Foundation (CNCF)
Pisarz techniczny:: Shriti
Nazwa projektu:: Ulepsz dokumentację dotyczącą SMI i powiązanych z nimi siatek usług
Długość projektu:: Standardowa długość (3 miesiące)

Opis projektu

Technologia siatki usług ma na celu dostarczanie wartości coraz większej liczbie usług poprzez spełnianie wszystkich potrzeb w zakresie bezpieczeństwa, zarządzania i monitorowania. Interfejs siatki usług (SMI) definiuje zestaw interfejsów API dla najczęstszych przypadków użycia siatki usług (zasady ruchu, telemetria i przenoszenie) i umożliwia zgodność między siatkami usług, które są dedykowanymi warstwami infrastruktury do obsługi komunikacji między usługami w środowisku mikroserwisów. Standaryzacja tych interfejsów zwiększy wygodę użytkowników, dlatego w przyszłości celem SMI i powiązanych z nimi usług jest cel.

Bieżący stan:

Przewodniki użytkownika: SMI to stosunkowo nowy projekt piaskownicy, przekazany CNCF w kwietniu 2020 r. W związku z tym brakuje dokumentacji dla użytkowników. Meshery to platforma zarządzania usługami, która umożliwia przeprowadzanie analiz porównawczych wydajności wszystkich rodzajów usług, co ułatwia wdrażanie, konfigurację, działanie i zarządzanie wydajnością różnych siatek usług. Obejmuje zbieranie i wyświetlanie wskaźników z aplikacji działających na bazie dowolnej siatki usług. Na początek chcę zacząć od przewodnika po Meshery, który będzie punktem wyjścia dla całej społeczności użytkowników SMI.

Samouczki dla użytkowników: Wśród istniejących platform SMI: Przykładowa aplikacja o nazwie Learn Layer5 służy obecnie jako urządzenie do nauki dla SMI i jako przykładowa aplikacja do weryfikacji specyfikacji SMI.Poza tym projekty SMI całkowicie nie mają samouczków dla użytkowników, co stanowi poważną przeszkodę ze względu na wysoce techniczny charakter projektów. Meshery to idealna aplikacja do prezentowania korzyści i wykorzystania SMI i powiązanych z nimi sieci usług. Dlatego właśnie będę jej używać jako podstawowego narzędzia do prezentowania funkcji SMI.

Dokumentacja API: Obecnie nie istnieje. SMI i różne powiązane projekty mają punkty końcowe API zdefiniowane na platformie. Na przykład punkty końcowe Meshery są zdefiniowane na serwerze.go (https://github.com/layer5io/meshery/blob/master/router/server.go), ale nie są one odpowiednio komentowane ani udokumentowane na zewnątrz. Ten problem można rozwiązać, dostarczając obszernej dokumentacji interfejsów API, a także dodając możliwości testowania punktów końcowych i podglądu ich funkcji przez użytkowników.

Analiza:

Samouczki użytkownika są tworzone, aby umożliwić użytkownikowi zaangażowanie i przetestowanie Oprogramowania. Muszą być interaktywne i estetyczne, aby przyciągać uwagę użytkownika, a co najważniejsze – łatwe w użyciu.

Jednak w przypadku tworzenia i hostowania podręczników użytkownika zalecamy użycie bardziej zaawansowanego formatu, ponieważ przewodniki użytkownika często pełnią rolę poradnika lub miejsca szybkiego rozwiązywania problemów. Zamiast być interaktywne, należy nadać im odpowiednią strukturę oraz zadbać o poprawę przejrzystości, spójności i dobrego przepływu użytkowników.

Możliwym rozwiązaniem tego problemu jest utworzenie osobnych samouczków użytkownika z wykorzystaniem Google Codelabs i niezależnego Przewodnika użytkownika z pomocą Jekyll. Na koniec zintegrowanie tych materiałów z dokumentacją interfejsu API w celu zapewnienia odpowiedniego działania zarówno użytkownikom końcowym, jak i przyszłym współpracownikom.

Docelowi odbiorcy: projekty SMI zapewniają praktyki w zakresie wdrażania i operacji, środowiska edukacyjne i porównania wydajności do wszystkich należących do nich projektów. Dotyczą one zarówno osób fizycznych, jak i organizacji.

Przewodniki użytkownika: będę skierowany do początkujących użytkowników, nie zakładając, że mają wcześniejszą wiedzę informatyczną. Grupa docelowa: początkujący użytkownicy Powód: używany głównie jako obszerny przewodnik, który trzeba aktualizować z biegiem czasu. Obejmuje to szczegółowe wyjaśnienia i przydatne wskazówki, dzięki którym użytkownik będzie miał wszystkie informacje niezbędne do skonfigurowania siatki usług i korzystania z niej. Przewodnik będzie bardziej atrakcyjny i przyjazny dla użytkowników, dodając do niego filmy, zdjęcia, zrzuty ekranu i GIF-y tam, gdzie będzie to konieczne.

Samouczki dla użytkownika: Cel: Początkujący użytkownicy Cel: należy skupić się na tym, aby samouczki były atrakcyjne i estetyczne, aby utrzymać uwagę użytkownika i umożliwić płynne uruchomienie oprogramowania, co pozwoli na lepsze zrozumienie interfejsu siatki usług.

Dokumentacja punktów końcowych API: Cel: zaawansowani użytkownicy Powód: ta sekcja dotyczy korzystania z bardziej złożonych funkcji siatki usług, która jest dla zaawansowanych użytkowników z podstawową wiedzą na temat IT. Doświadczeni użytkownicy szukają zwięzłych samouczków, które w razie potrzeby mogą posłużyć jako przewodniki. Dokumentacja punktów końcowych powinna być napisana w taki sposób, aby ułatwić jej aktualizowanie bez negatywnego wpływu na jej dokładność i spójność. Zaleca się, aby proces ten odbywał się automatycznie.

Zasoby: Samouczki dla użytkowników: ćwiczenia z programowania Google Developers – umożliwiające tworzenie interaktywnych i kompleksowych samouczków dla użytkowników. Zalety: – Możliwość tworzenia samouczków na temat piaskownicy. – Organizacja ma praktyczne podejście. - Napisanie przy użyciu Dokumentów Google z obsługą tekstu Markdown. – Możliwość monitorowania dzięki Google Analytics. – Łatwe obserwowanie ruchu użytkowników. – Łatwo obsługiwać. Tworzy atrakcyjne estetyczne samouczki, które pozwalają użytkownikowi na bezpośrednią interakcję z programem bez konieczności angażowania się w aplikację.

Laboratorium Google Codelabs można ulepszać i łatwo wdrażać za pomocą projektu CLaaT (Codelabs as a Thing) – program udostępnia narzędzie wiersza poleceń służące do konwertowania samouczków napisanych w dokumencie Google za pomocą formatu Markdown na format HTML (Codelabs).

Przewodniki użytkownika: Jekyll – istniejąca dokumentacja meshery.io, którą znajdziesz tutaj, jest hostowana w Jekyll i wykorzystuje motyw Docsy Jekyll. Wykorzystuje kod Markdown, płyny, HTML i CSS do tworzenia gotowych do hostowania, statycznych witryn i działa w środowisku programistycznym Ruby. Zalety: – Możliwość hostowania witryn bezpośrednio z repozytoriów GitHuba. – Projekt jest wspierany przez bardzo aktywną społeczność. – Przewodniki użytkownika i ulepszenia można łatwo dodawać do istniejącej dokumentacji SMI i Meshery bez konieczności migracji do innej platformy.

Dokumentacja API: Do utworzenia dokumentacji API dla SMI i Meshery zostanie użyty Swagger (nazywany też Swaggo). Jest to eleganckie rozwiązanie do tworzenia dokumentów interfejsu API. Korzyści: – Dokumentacja projektu interfejsu API: dzięki niej dokumentacja jest aktualna wraz z rozwojem interfejsu API. – Dokumentacja projektu API: może być generowana automatycznie na podstawie definicji interfejsu API. – Obsługa wielu wersji dokumentacji – Dostosowane projekty interfejsów API

Cele projektu: – Korzystanie z Google Developer Codelabs do tworzenia interaktywnych samouczków dla użytkowników korzystających z SMI i powiązanych z nimi sieci usług z wykorzystaniem Meshery jako narzędzia. – Utwórz przewodnik dla użytkownika z wykorzystaniem Jekyll do tworzenia siatek usług. – Użyj narzędzia Swagger, aby wygenerować dokumentację punktów końcowych interfejsu API dla SMI. – Zadbaj o to, aby społeczność projektowa była wspierana przez innych użytkowników, tak aby przyszli i obecni użytkownicy oraz deweloperzy mogli bez trudu je uzupełniać, kierując się wskazówkami i moderacją społeczności SMI.

Oś czasu: proponowany harmonogram znajduje się tutaj: https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#bookmark=kix.j1b6m64eubsl

Struktura: Proponowaną strukturę Przewodnika użytkownika można znaleźć tutaj: https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing

Dlaczego ten projekt? Społeczność siatki usług rozwija się w szybkim tempie, co wynika z niedawnej integracji z CNCF w formie projektu piaskownicy. Obecnie w projekcie pojawia się coraz mniej dokumentów zarówno dla użytkowników, jak i deweloperów. W przeszłości zdarzyło mi się wypróbować różne siatki usług, w tym linkerD z aplikacją Emotikony Emotikony, Istio w aplikacji z informacjami o książce oraz Konsul Hashicorp. Wypróbowałem też podział ruchu SMI i wdrożyłem różne reguły weryfikacji w konfiguracji siatki usług. Proces nauki jest fascynujący, ale ma bardzo techniczny charakter. Może zniechęcić zarówno nowych użytkowników, jak i deweloperów, którzy chcą założyć pierwsze kroki w społeczności siatki usług lub zacząć korzystać z takich sieci w swoich osobistych lub zawodowych projektach. Chciałabym wypełnić tę lukę, co można zrobić tylko przy pomocy skutecznych i dobrze udokumentowanych przewodników i samouczków.