Ta strona zawiera szczegółowe informacje o projekcie polegającym na pisaniu tekstów technicznych, który został zaakceptowany w ramach Google Season of Docs.
Podsumowanie projektu
- Organizacja open source
- Cloud Native Computing Foundation (CNCF)
- Pisarz techniczny:
- Shriti
- Nazwa projektu:
- Ulepszenie dokumentacji dotyczącej SMI i powiązanych sieci usług
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Technologia Service Mesh ma na celu zapewnienie wartości coraz większej liczbie usług poprzez zaspokojenie wszystkich potrzeb związanych z bezpieczeństwem, zarządzaniem i monitorowaniem. Interfejs Service Mesh Interface (SMI) definiuje zestaw interfejsów API do najczęstszych zastosowań sieci usług (polityka ruchu, telemetria i przesuwanie) oraz zapewnia zgodność między sieciami usług, które są dedykowanymi warstwami infrastruktury do obsługi komunikacji między usługami w środowisku mikrousług. Standaryzacja tych interfejsów zapewni lepsze wrażenia użytkowników, dlatego jest to przyszły cel SMI i powiązanych sieci usług.
Obecny stan:
Przewodniki użytkownika: SMI to stosunkowo nowy projekt piaskownicy, który został przekazany do CNCF w kwietniu 2020 r. W efekcie projekt nie zawiera dokumentacji dla użytkowników. Meshery to platforma do zarządzania usługami z benchmarkami wydajności dla wszystkich rodzajów usług, która ułatwia wdrażanie, konfigurowanie, działanie i zarządzanie wydajnością różnych sieci usług. Umożliwia też zbieranie i wyświetlanie danych z aplikacji działających na dowolnej sieci usług. Dlatego na początek chcę przedstawić przewodnik po Meshery, który posłuży jako punkt wyjścia dla całej społeczności użytkowników SMI.
Samouczki dla użytkowników: Wśród istniejących platform SMI: aplikacja Learn Layer5 służy obecnie jako urządzenie do nauki SMI i jako przykładowa aplikacja do weryfikacji zgodności ze specyfikacją SMI.Poza tym w projektach SMI całkowicie brakuje samouczków dla użytkowników, co jest poważną przeszkodą ze względu na wysoce techniczny charakter projektów. Meshery to idealna aplikacja do prezentowania zalet i zastosowania SMI oraz powiązanych z nim sieci usług. Dlatego użyję jej jako podstawowego narzędzia do omówienia funkcji SMI.
Dokumentacja interfejsu API: obecnie nie istnieje. SMI i różne powiązane z nim projekty mają zdefiniowane punkty końcowe interfejsu API na platformie. Przykładowo Meshery ma punkty końcowe zdefiniowane w pliku server.go (https://github.com/layer5io/meshery/blob/master/router/server.go), ale nie są one dobrze skomentowane ani udokumentowane na zewnątrz. Można rozwiązać ten problem, korzystając ze szczegółowej dokumentacji interfejsu API, oraz dodając sposoby na testowanie przez użytkowników punktów końcowych i wyświetlanie podglądu ich funkcji.
Analiza:
Samouczki dla użytkowników są tworzone, aby umożliwić im zapoznanie się z oprogramowaniem i przetestowanie go. Muszą być interaktywne i estetyczne, aby przyciągać uwagę użytkowników, a co najważniejsze – łatwe w użyciu.
Jednak w przypadku tworzenia lub hostowania przewodników dla użytkowników zalecamy użycie bardziej zaawansowanego formatu, ponieważ przewodniki te często pełnią funkcję przewodnika po funkcjach lub miejsca, w którym można szybko znaleźć rozwiązanie problemu. Nie muszą być interaktywne, ale muszą być dobrze ustrukturyzowane i skupione na zwiększeniu przejrzystości, spójności i płynności ścieżki użytkownika.
Możliwym rozwiązaniem tego może być utworzenie osobnych samouczków dla użytkowników za pomocą Google Codelabs i niezależnego przewodnika użytkownika we współpracy z firmą Jekyll, a następnie zintegrowanie ich z dokumentacją interfejsu API, aby zapewnić zarówno użytkownikom, jak i przyszłym współpracownikom satysfakcjonujące środowisko.
Grupa docelowa: projekty SMI zapewniają metody wdrażania i działania operacyjnego, środowisko uczenia się oraz testy porównawcze wydajności dla wszystkich projektów, które się do nich zaliczają. Jest ona przeznaczona zarówno dla osób fizycznych, jak i organizacji.
Przewodniki użytkownika: kieruję reklamy do początkujących użytkowników, którzy nie mają wcześniejszej wiedzy z zakresu IT. Użytkownicy początkujący. Powód: służy głównie jako obszerny przewodnik, który z czasem będzie trzeba aktualizować. Będzie on zawierać szczegółowe wyjaśnienia i przydatne wskazówki, aby użytkownik miał wszystkie informacje potrzebne do konfiguracji i obsługi sieci usług. W razie potrzeby dodamy filmy, zdjęcia, zrzuty ekranu i GIF-y, aby ułatwić użytkownikom korzystanie z pomocy.
Samouczki dla użytkowników: Grupa docelowa: początkujący użytkownicy Uzasadnienie: celem będzie uczynienie samouczków atrakcyjnych i estetycznych, aby przykuć uwagę użytkownika i umożliwić płynne testowanie oprogramowania, co pozwoli lepiej zrozumieć interfejs Service Mesh.
Dokumentacja punktu końcowego interfejsu API: Użytkownicy zaawansowani: ta sekcja skupia się na korzystaniu z bardziej złożonych funkcji sieci usług, które są bardziej interesujące dla zaawansowanych użytkowników z podstawowymi umiejętnościami IT. Zaawansowani użytkownicy będą szukać zwięzłych samouczków, które w razie potrzeby mogą też służyć jako przewodniki. Dokumentacja punktu końcowego powinna być napisana w taki sposób, aby można ją było łatwo aktualizować bez utraty dokładności i spójności. Najlepiej, aby był to proces zautomatyzowany.
Zasoby: Samouczki dla użytkowników: Google Developers Codelab – służy do tworzenia interaktywnych i wyczerpujących samouczków dla użytkowników. Korzyści: - możesz tworzyć samouczki dotyczące piaskownicy. – ma praktyczny charakter; – napisany w Dokumentach Google i obsługujący format Markdown. – Można je monitorować za pomocą Google Analytics – łatwo obserwować ruch użytkowników. – łatwość obsługi. Tworzenie atrakcyjnych wizualnie samouczków, które umożliwiają użytkownikowi bezpośrednie zapoznanie się z oprogramowaniem bez konieczności ponoszenia bezpośrednich kosztów.
Google Codelabs można rozbudować i łatwo wdrożyć za pomocą projektu CLaaT (Codelabs as a Thing) — to program udostępniający narzędzie wiersza poleceń używane do konwertowania samouczków napisanych w Dokumentach Google przy użyciu formatu Markdown na format Codelabs (HTML).
Przewodniki użytkownika: Jekyll – istniejąca dokumentacja meshery.io, którą znajdziesz tutaj, jest hostowana na Jekyll i używa motywu Docsy Jekyll. Korzysta z Markdowna, liquida, HTML-a i CSS-a, aby tworzyć gotowe do hostowania strony internetowe. Działa w środowisku programistycznym Ruby. Zalety: – Możliwość hostowania witryn bezpośrednio z repozytoriów GitHub. – To dobrze wspierany projekt z bardzo aktywną społecznością – Instrukcje dla użytkowników i ulepszone funkcje można po prostu dodać do istniejącej dokumentacji SMI i Meshery bez konieczności przenoszenia na inną platformę.
Dokumentacja interfejsu API: Swagger (lub Swaggo) będzie używany do tworzenia dokumentacji interfejsu API dla SMI i Meshery. Jest to eleganckie rozwiązanie do pisania dokumentów API. Zalety: – Dokumentacja projektu interfejsu API: zapewnia aktualność dokumentacji w miarę rozwoju interfejsu API. – Dokumentacja z projektu interfejsu API: może być generowana automatycznie na podstawie definicji interfejsu API. – Obsługa wielu wersji dokumentacji – Dostosowane projekty interfejsów API
Cele projektu: – Skorzystaj z programu Codelabs w Google Developer, aby utworzyć interaktywne samouczki dla użytkowników dotyczące SMI i powiązanych siatek usług z użyciem Meshery jako narzędzia. – Utwórz przewodnik użytkownika z użyciem Jekylla do obsługi siatek usług. – Użyj Swaggera do wygenerowania dokumentacji punktu końcowego interfejsu API dla SMI. – Utwórz projekt oparty na społeczności, aby obecni i przyszli użytkownicy lub deweloperzy mogli łatwo go rozwijać pod nadzorem i moderacji społeczności SMI.
Harmonogram: Proponowany harmonogram znajdziesz tutaj: https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#bookmark=kix.j1b6m64eubsl
Struktura: Proponowaną strukturę Przewodnika użytkownika znajdziesz tutaj: https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing
Dlaczego ten projekt? Społeczność siatka usług rozwija się błyskawicznie, co jest możliwe dzięki niedawnej integracji z CNCF jako projekt piaskownicy. Jednak w przypadku tego projektu brakuje dokumentacji, zarówno dla użytkowników, jak i dla deweloperów. W przeszłości zajmowałem się różnymi usługami typu service mesh, w tym linkerD z aplikacją EmojiVoto, Istio z aplikacją bookinfo i narzędziem Consul firmy Hashicorp. Próbowaliśmy też podzielić ruch w SMI i wdrożyć różne reguły walidacji w konfiguracji sieci usług. Proces uczenia się jest fascynujący, ale ma wysoce techniczny charakter i może zniechęcić nowych użytkowników oraz deweloperów, którzy chcą wejść do społeczności siatki usług lub wykorzystać siatki usług do własnych lub zawodowych projektów. Chciałabym wypełnić tę lukę, co można zrobić tylko dzięki skutecznym i dobrze udokumentowanym przewodnikom i samouczkom.