Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.
Riepilogo del progetto
- Organizzazione open source:
- Cloud Native Computing Foundation (CNCF)
- Technical writer:
- Shriti
- Nome progetto:
- Migliora la documentazione di SMI e mesh di servizi correlati
- Durata del progetto:
- Durata standard (3 mesi)
Project description
La tecnologia mesh di servizi mira essenzialmente a fornire valore al numero crescente di servizi, gestendo tutte le tue esigenze di sicurezza, gestione e monitoraggio. SMI (Service Mesh Interface) definisce un insieme di API per i casi d'uso più comuni di mesh di servizi (criteri di traffico, telemetria e spostamenti) e consente la compatibilità tra mesh di servizi, che sono livelli di infrastruttura dedicati per la gestione della comunicazione tra servizi in un ambiente di microservizi. La standardizzazione di queste interfacce fornirà un'esperienza migliorata per l'utente finale e, quindi, è un obiettivo futuro per SMI e mesh di servizi correlati.
Stato attuale:
Guide dell'utente: SMI è un progetto sandbox relativamente nuovo, donato al CNCF ad aprile 2020. Di conseguenza, il progetto è privo di documentazione per l'utente finale. Meshery è un piano di gestione dei servizi con benchmarking delle prestazioni per tutti i tipi di servizi che facilita l'adozione, la configurazione, il funzionamento e la gestione delle prestazioni di mesh di servizi diversi. Inoltre, incorpora la raccolta e la visualizzazione delle metriche delle applicazioni in esecuzione su qualsiasi mesh di servizi. Pertanto, vorrei iniziare con una guida a Meshery, che servirà da punto di partenza per l'intera community di utenti 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 su cui eseguire la convalida delle specifiche SMI. Meshery è l'applicazione perfetta per mostrare i vantaggi e l'utilizzo di SMI e dei relativi mesh di servizi, motivo per cui lo userò come strumento di base per mostrare le caratteristiche di SMI.
Documentazione API: Inesistente al momento. SMI e vari progetti correlati hanno i propri endpoint API definiti su una piattaforma; ad esempio, Meshery ha i suoi endpoint definiti su server.go (https://github.com/layer5io/meshery/blob/master/router/server.go), ma non sono né ben commentati o 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 i suoi endpoint e visualizzare l'anteprima delle sue funzionalità.
Analisi:
I tutorial utente vengono creati per consentire all'utente di interagire e testare il software. Devono essere interattivi ed esteticamente attraenti per mantenere l'attenzione dell'utente e, soprattutto, devono essere facili da usare.
Tuttavia, per la scrittura o l'hosting di guide dell'utente, è consigliabile optare per un formato più adatto, in quanto queste ultime spesso fungono da guida di riferimento o da cui trovare rapidamente una soluzione ai problemi. Anziché essere interattivi, devono essere ben strutturati e concentrarsi sul miglioramento della chiarezza, della coerenza e di un buon flusso di utenti.
Una possibile soluzione a questo problema sarebbe creare tutorial per gli utenti separati utilizzando i codelab di Google e una guida dell'utente indipendente con l'aiuto di Jekyll e infine integrarli insieme alla documentazione dell'API per offrire un'esperienza completa sia all'utente finale che ai futuri collaboratori.
Pubblico di destinazione: i progetti SMI forniscono pratiche operative e di deployment, ambienti di apprendimento e benchmark delle prestazioni per tutti i progetti sottostanti. Si rivolge a privati e organizzazioni.
Guide dell'utente: sceglierò come target gli utenti principianti, senza presunzioni di conoscenze IT preesistenti. Target: utenti principianti Motivo: utilizzato principalmente come vasta guida di riferimento, che dovrà essere aggiornata con il tempo. Includerà spiegazioni approfondite e suggerimenti utili per assicurarsi che l'utente disponga di tutte le informazioni necessarie per configurare e utilizzare un mesh di servizi. La Guida sarà resa più coinvolgente e facile da usare aggiungendo video, immagini, screenshot e GIF, se necessario.
Tutorial per gli utenti: Target: utenti principianti Motivo: l'obiettivo sarà rendere i tutorial coinvolgenti ed esteticamente accattivanti per mantenere l'attenzione dell'utente e consentire un test senza problemi del software, il che porterà a una migliore comprensione dell'interfaccia mesh di servizi.
Documentazione relativa agli endpoint API: Target: utenti avanzati Motivo: questa sezione si concentra sull'utilizzo delle funzionalità più complesse del mesh di servizi, che sono maggiormente nell'interesse degli utenti avanzati con un livello di conoscenza di base dell'IT. Gli utenti esperti cercheranno tutorial concisi da utilizzare anche come guide di riferimento, se necessario. La documentazione dell'endpoint deve essere scritta in modo da facilitare l'aggiornamento senza comprometterne l'accuratezza o la coerenza. Si tratta preferibilmente di una procedura automatica.
Risorse: Tutorial per gli utenti: Codelab di Google Developers. Utilizzato per creare tutorial interattivi e completi per l'utente finale. Vantaggi: - consente di creare tutorial sandbox. - Ha un approccio pratico. - Scritta utilizzando Documenti Google e con supporto del testo Markdown. - Possono essere monitorati utilizzando Google Analytics - Facile osservare il traffico degli utenti. - Facile da usare. Produce tutorial esteticamente piacevoli 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): si tratta di un programma che offre uno strumento a riga di comando utilizzato per convertire nel formato codelab (HTML) tutorial scritti in un documento Google utilizzando Markdown.
Guide dell'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 eseguiti in un ambiente di sviluppo Ruby. Vantaggi: - Possibilità di ospitare siti direttamente dai repository GitHub. - Questo è un progetto ben supportato con una community molto attiva - Le guide per l'utente e i miglioramenti possono essere semplicemente aggiunti alla documentazione esistente di SMI e Meshery, senza doversi preoccupare della migrazione a un'altra piattaforma.
Documentazione dell'API: Saggero (in alternativa, Swaggo) verrà utilizzato per creare la documentazione dell'API per SMI e Meshery. Si tratta di una soluzione elegante per la scrittura di documenti API. Vantaggi: - Documentazione dalla progettazione dell'API: garantisce che la documentazione sia sempre aggiornata man mano che l'API si evolve. - Documentazione dalla progettazione dell'API: può essere generata automaticamente dalle definizioni dell'API. - Gestione di più versioni della documentazione - Design personalizzati delle API
Obiettivi del progetto: - Utilizzare i codelab per sviluppatori di Google per creare tutorial interattivi per l'utente finale per SMI e mesh di servizi correlati utilizzando Meshery come strumento. - Creare una guida per l'utente finale utilizzando Jekyll per i mesh di servizi. - Utilizza Swagger per generare la documentazione degli endpoint API per l'SMI. - Incoraggia la community del progetto in modo che gli utenti o gli sviluppatori futuri e attuali possano facilmente continuare ad aggiungerli sotto la guida e la moderazione della community SMI.
Sequenza temporale: La sequenza temporale 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 del mesh di servizi si sta espandendo a un ritmo rapidissimo, resa possibile dalla sua recente integrazione come progetto sandbox nel CNCF. Tuttavia, il progetto sta assistendo a una grave carenza di documentazione, sia per gli utenti finali che per gli sviluppatori. In passato ho giocato con vari mesh di servizi, tra cui linkerD con l'app EmojiVoto, Istio con la sua applicazione bookinfo e il console di Hashicorp. Ho anche provato la suddivisione del traffico SMI e ho implementato varie regole di convalida sulla configurazione del mesh di servizi. Il processo di apprendimento è affascinante ma altamente tecnico e può essere scoraggiante sia per i nuovi utenti che per gli sviluppatori, che cercano di muovere i primi passi nella community dei mesh di servizi o di utilizzare mesh di servizi per i loro progetti personali o professionali. Vorrei colmare questo divario, che può essere fatto solo con guide e tutorial efficienti e ben documentati.