Questa pagina contiene i dettagli di un progetto di documentazione tecnica accettato per la stagione della documentazione di Google.
Riepilogo del progetto
- Organizzazione open source:
- Cloud Native Computing Foundation (CNCF)
- Technical Writer:
- Shriti
- Nome del progetto:
- Migliorare la documentazione di SMI e dei relativi mesh di servizi
- Durata del progetto:
- Durata standard (3 mesi)
Project description
La tecnologia Service Mesh ha lo scopo principale di fornire valore al numero crescente di servizi, gestendo tutte le esigenze di sicurezza, gestione e monitoraggio. Service Mesh Interface (SMI) definisce un insieme di API per i casi d'uso più comuni delle mesh di servizi (criteri di traffico, telemetria e spostamento) e abilita la compatibilità tra le mesh di servizi, che sono livelli di infrastruttura dedicati per la gestione della comunicazione da servizio a servizio in un ambiente di microservizi. La standardizzazione di queste interfacce offrirà un'esperienza utente finale migliorata e, pertanto, è un obiettivo futuro per le SMI e i relativi mesh di servizi.
Stato attuale:
Guide per l'utente: SMI è un progetto sandbox relativamente nuovo, donato a CNCF ad aprile 2020. Di conseguenza, il progetto non dispone della documentazione per l'utente finale. Meshery è un piano di gestione dei servizi con benchmarking delle prestazioni per tutti i tipi di servizi che semplifica l'adozione, la configurazione, il funzionamento e la gestione del rendimento di diversi mesh di servizi e incorpora la raccolta e la visualizzazione delle metriche delle applicazioni in esecuzione su qualsiasi mesh di servizi. Pertanto, vorrei iniziare con una guida per Meshery, che fungerà da punto di partenza per l'intera community di utenti di SMI.
Tutorial per gli utenti: tra le piattaforme SMI esistenti: l'applicazione di esempio Learn Layer5 attualmente funge da dispositivo di apprendimento per SMI e da applicazione di esempio per eseguire la convalida delle specifiche SMI.Ma per il resto, i progetti SMI sono completamente privi di tutorial per gli utenti finali, il che rappresenta un grave ostacolo a causa della natura altamente tecnica dei progetti. Meshery è l'applicazione perfetta per mostrare i vantaggi e l'utilizzo di SMI e dei relativi mesh di servizi, motivo per cui lo utilizzerò come strumento di base per mostrare le funzionalità di SMI.
Documentazione dell'API: non esistente al momento. SMI e vari progetti correlati hanno i propri endpoint API definiti su una piattaforma; ad esempio, Meshery ha i suoi endpoint definiti in server.go (https://github.com/layer5io/meshery/blob/master/router/server.go), ma non sono né ben commentati né documentati esternamente. Questo problema può essere risolto con una documentazione significativa delle API e può essere migliorato aggiungendo modi per consentire agli utenti di testare gli endpoint e visualizzare l'anteprima delle funzionalità.
Analisi:
I tutorial per gli utenti vengono creati per consentire all'utente di interagire con il software e di eseguirne una prova. Devono essere interattivi ed esteticamente accattivanti per attirare l'attenzione dell'utente e, soprattutto, essere facili da usare.
Tuttavia, per scrivere o ospitare guide dell'utente, è consigliabile un formato più adatto, in quanto le guide dell'utente spesso fungono da guida di riferimento o da luogo in cui trovare una soluzione rapida ai problemi. Anziché essere interattivi, devono essere ben strutturati e concentrarsi sul miglioramento della chiarezza, della coerenza e di un buon flusso utente.
Una possibile soluzione a questo problema sarebbe creare tutorial per gli utenti separati utilizzando Google Codelabs e una guida utente indipendente con l'aiuto di Jekyll e infine integrarli con la documentazione dell'API per offrire un'esperienza completa sia all'utente finale che ai futuri collaboratori.
Pubblico di destinazione: i progetti SMI forniscono pratiche di implementazione e operatività, ambienti di apprendimento e benchmark sul rendimento a tutti i progetti sottostanti. Si rivolge sia ai privati che alle organizzazioni.
Guide per l'utente: sceglierò come target gli utenti principianti, senza presumere conoscenze IT preesistenti da parte dell'utente. Destinazione: utenti principianti Motivo: utilizzata principalmente come ampia guida di riferimento, che dovrà essere aggiornata nel tempo. Saranno incluse spiegazioni approfondite e suggerimenti utili per assicurarsi che l'utente disponga di tutte le informazioni necessarie per configurare e utilizzare un service mesh. La Guida diventerà più coinvolgente e facile da usare aggiungendo video, immagini, screenshot e GIF, se necessario.
Tutorial per gli utenti: Destinatari: utenti principianti Motivo: l'obiettivo sarà rendere i tutorial coinvolgenti ed esteticamente accattivanti per attirare l'attenzione dell'utente e consentire un'esecuzione di prova senza problemi del software, che porterà a una migliore comprensione dell'interfaccia Service Mesh.
Documentazione relativa agli endpoint API: Destinatari: utenti avanzati Motivo: questa sezione si concentra sull'utilizzo delle funzionalità più complesse del service mesh, che è più nell'interesse degli utenti avanzati con un livello di conoscenza IT di base. Gli utenti avanzati cercheranno tutorial concisi che, se necessario, possono essere utilizzati anche come guide di riferimento. La documentazione relativa agli Endpoint deve essere redatta in modo tale da facilitarne l’aggiornamento senza comprometterne l’accuratezza o la coerenza. È preferibile che si tratti di una procedura automatica.
Risorse: Tutorial per gli utenti: Codelab per Google Developers, utilizzato per creare tutorial interattivi e completi per gli utenti finali. Vantaggi: - Può produrre tutorial sulla sandbox. - Ha un approccio pratico. - È stato scritto usando Documenti Google e supporta il testo Markdown. - Possono essere monitorati utilizzando Google Analytics - È facile osservare il traffico degli utenti. - Facile da usare. Produce tutorial esteticamente accattivanti che consentono all'utente di interagire direttamente con il software senza alcun investimento diretto.
Google Codelab può essere migliorato e implementato facilmente utilizzando il progetto CLaaT (Codelab as a Thing), un programma che offre uno strumento a riga di comando utilizzato per convertire i tutorial scritti in Documenti Google utilizzando Markdown nel formato codelab (HTML).
Guide per l'utente: Jekyll: la documentazione esistente per meshery.io, disponibile qui, è ospitata su Jekyll e utilizza il tema Docsy Jekyll. Utilizza Markdown, liquid, HTML e CSS per produrre siti web statici pronti per l'hosting e funziona in un ambiente di sviluppo Ruby. Vantaggi: - Puoi ospitare i siti direttamente dai repository GitHub. - Questo è un progetto ben supportato con una community molto attiva - È possibile aggiungere facilmente guide dell'utente e miglioramenti alla documentazione esistente di SMI e Meshery, senza doversi preoccupare della migrazione su un'altra piattaforma.
Documentazione API: per la creazione della documentazione dell'API per SMI e Meshery verrà utilizzato Swagger (in alternativa, Swaggo). È una soluzione elegante per scrivere documenti API. Vantaggi: - Documentazione dal design dell'API: garantisce che la documentazione rimanga aggiornata man mano che l'API si evolve. - Documentazione del design dell'API: può essere generata automaticamente dalle definizioni dell'API. - Gestire più versioni della documentazione - Progetti API personalizzati
Scopi del progetto: - Utilizza i Codelab per sviluppatori Google per creare tutorial interattivi per gli utenti finali per gli SMI e i relativi mesh di servizi utilizzando Meshery come strumento. - Crea una guida per gli utenti finali utilizzando Jekyll per i mesh di servizi. - Utilizza Swagger per generare la documentazione degli endpoint API per SMI. - Rendi il progetto basato sulla community in modo che gli utenti o gli sviluppatori attuali e futuri possano continuare facilmente ad aggiungervi contenuti sotto la guida e la moderazione della community SMI.
Cronologia: la cronologia proposta è disponibile qui: https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#bookmark=kix.j1b6m64eubsl
Struttura: la struttura proposta per la Guida dell'utente è disponibile qui: https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing
Perché questo progetto? La community di mesh di servizi si sta espandendo a un ritmo rapidissimo, grazie alla recente integrazione come progetto sandbox nel CNCF. Tuttavia, il progetto sta registrando una grave carenza di documentazione, sia per gli utenti finali sia per gli sviluppatori. In passato ho provato vari mesh di servizi, tra cui linkerD con l'app EmojiVoto, Istio con la sua applicazione bookinfo e Consul di Hashicorp. Ho anche provato la suddivisione del traffico SMI e ho implementato varie regole di convalida nella configurazione del mio service mesh. Il processo di apprendimento è affascinante, ma altamente tecnico e può scoraggiare i nuovi utenti e gli sviluppatori che vogliono fare i primi passi nella community di service mesh o utilizzare i service mesh per i propri progetti personali o professionali. Vorrei colmare questa lacuna, il che può essere fatto solo con guide e tutorial efficienti e ben documentati.