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:
- Syam Sundar K
- Nome del progetto:
- Esempi di Kubectl più numerosi e migliori
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Lo scopo di questo progetto è quello di migliorare la scheda di riferimento e i documenti di riferimento esistenti di kubectl.
Questi sono gli obiettivi principali di questo progetto: • Creare esempi kubectl sempre più numerosi e migliori. • Aggiungi esempi di kubectl al cheat sheet di kubectl. • Ristrutturare la documentazione di kubectl per renderla il più utile possibile.
Obiettivo I: esempi per kubectl:
Collaborerà strettamente con i gruppi di interesse speciale dell'interfaccia a riga di comando per comprendere il contesto e il tipo di esempi più richiesti dagli utenti di Kubernetes e per documentarli. Possono essere migliorati i comandi kubectl esistenti nel cheat sheet o aggiunti nuovi comandi.
Obiettivo II: maggiore utilità dei documenti:
Per aumentare l'utilità dei documenti, è possibile fare quanto segue:
• Eliminazione delle difficoltà dei principianti • Riorganizzazione del comando kubectl in un determinato ordine per garantire continuità nel flusso logico
Elimina le difficoltà dei principianti con spiegazioni migliori a livello di comando / caso dell'utente. Sembra semplice, ma può influenzare notevolmente i principianti a continuare o interrompere il loro apprendimento. Ad esempio, quando ho iniziato a utilizzare Kubernetes tramite kubectl, non ero sicura delle differenze tra pod e deployment. Inizialmente ho implementato un servizio di backend scritto in nodejs. Dopo alcune ore volevo farlo, quindi ho provato a eliminare il pod, ma a causa della natura autoriparante dei pod, sono stati creati di nuovo. Non capivo cosa stesse succedendo e mi chiedevo perché il video veniva ricreato e non eliminato. Dopo alcune ricerche sul web, ho capito che l'eliminazione dei pod non è la stessa cosa dell'eliminazione di un deployment. A un occhio esperto potrebbe sembrare semplice, ma la spiegazione chiara che elimina questo tipo di ambiguità è ciò che distingue un buon documento da un ottimo documento.
Riorganizzare il comando kubectl in un determinato ordine per garantire la continuità del flusso logico. Se sei come me e credi fermamente nello storytelling, probabilmente ti starai chiedendo come inserire elementi di storytelling in un foglio di documenti che contiene un elenco di comandi di terminale. Io dico che si può fare. Tutto ciò che impariamo ha sempre un flusso logico, un punto di partenza e uno di arrivo, se vuoi. Kubectl, in quanto strumento a riga di comando, ha ovviamente una curva di apprendimento, che coincide con quella di Kubernetes stesso. Poiché quasi tutti iniziano il proprio percorso con Kubernetes tramite kubectl (tranne chi utilizza l'interfaccia utente web) e poiché la sua curva di apprendimento è strettamente associata a quella di Kubernetes, le documentazioni possono essere migliorate notevolmente semplicemente cambiando l'ordine di questi comandi e introducendo elementi di narrazione. Ad esempio, funzionalità come la scalabilità automatica orizzontale dei pod possono essere spiegate dopo aver spiegato le risorse con esempi e illustrazioni reali.
Obiettivo III: miglioramenti all'usabilità della documentazione:
La recente migrazione del sito web di Kubernetes a Docsy Hugo è fantastica e rappresenta un enorme cambiamento dal punto di vista della documentazione. Nonostante la migrazione sia andata a buon fine, c'è ancora spazio per molti miglioramenti nello spazio dei documenti.
Ecco alcune modifiche che ti consiglio di apportare:
• Scorri automaticamente il riquadro sinistro fino alla sezione attualmente attiva nei documenti principali. Questa opzione può essere utile per tenere traccia delle sezioni attuali, future e passate. • Copia negli appunti: alcuni comandi possono essere lunghi e la funzionalità di copia può essere utile quando si utilizzano questi tipi di comandi. • Formattazione dei contenuti dei file doc: dopo la migrazione, i contenuti di alcune pagine non sono formattati correttamente. Ad esempio, la sezione Tipo di risorsa nella panoramica di kubectl. Ciò peggiora l'esperienza utente.
Si tratta di modifiche che possono migliorare l'esperienza utente sul sito web di Kubernetes e aumentare anche la produttività dell'utente.