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:
- Silvia Bianchi
- Nome progetto:
- Altri esempi di kubectl migliori
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Lo scopo di questo progetto è migliorare la scheda di riferimento e i documenti di riferimento kubectl esistenti.
Questi sono gli obiettivi finali di questo progetto: • Creare esempi kubectl migliori e più numerosi. • Aggiungere esempi di kubectl alla scheda di riferimento di kubectl. • Refactoring dei documenti kubectl per la massima utilità.
Obiettivo I: esempi per kubectl:
Lavoreremo a stretto contatto con i gruppi di interesse speciali dell'interfaccia a riga di comando per ottenere il contesto, il tipo di esempi più richiesti dagli utenti di Kubernetes e documentarlo. Ad esempio, puoi migliorare i comandi kubectl esistenti sulla scheda di riferimento o aggiungerne di nuovi.
Obiettivo II - Maggiore utilità dei documenti:
Per aumentare l'utilità dei documenti, è possibile:
• Eliminazione delle difficoltà dei principianti • Riorganizzazione del comando kubectl in un determinato ordine per garantire la continuità nel flusso logico
Elimina le difficoltà dei principianti migliorando i comandi o le spiegazioni dei casi dell'utente. Questo può sembrare semplice, ma può influenzare notevolmente i principianti riguardo alla prosecuzione o all'interruzione dell'apprendimento. Ad esempio, quando ho iniziato a utilizzare Kubernetes tramite kubectl, non ero sicura delle differenze tra pod e deployment. Inizialmente ho eseguito il deployment di un servizio di backend scritto in nodejs. Dopo alcune ore, ho deciso di disattivarlo, quindi ho provato a eliminare il pod, ma a causa della natura automatica dei pod sono stati creati di nuovo. Ero un po' sconcertato da ciò che stava accadendo e mi chiedevo perché veniva ricreato e non venisse eliminato. Dopo alcune ricerche sul web, ho capito che eliminare i pod non è la stessa cosa che eliminare un deployment. Per un occhio esperto potrebbe sembrare semplice, ma una 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à nel flusso logico. Se sei una persona come me che crede fermamente nello storytelling, probabilmente ti starai chiedendo come si fa a inserire gli elementi dello storytelling in un documento contenente un elenco di comandi del terminale, dico io, si può fare. Tutto ciò che impariamo ha sempre un flusso logico: un punto di partenza e un punto di arrivo, se vuoi. kubectl, in quanto strumento a riga di comando, ha ovviamente una curva di apprendimento, infatti coincide con la curva di apprendimento di Kubernetes stesso. Poiché quasi tutti iniziano il loro percorso con Kubernetes tramite kubectl (tranne le persone che utilizzano l'interfaccia utente web) e poiché la sua curva di apprendimento è strettamente accoppiata alla curva di apprendimento di Kubernetes, i documenti possono essere migliorati notevolmente cambiando l'ordine di questi comandi e introducendo gli elementi di storytelling. Supponiamo, per un'istanza, che funzionalità come la scalabilità automatica orizzontale dei pod possano essere spiegate dopo aver spiegato le risorse con esempi e illustrazioni reali.
Obiettivo III - Miglioramenti dell'usabilità di Documenti:
La recente migrazione del sito web Kubernetes a Docsy Hugo è fantastica e sta compiendo un enorme cambiamento dal punto di vista dei documenti. Sebbene la migrazione sia riuscita, c'è ancora spazio per molti miglioramenti nello spazio dei documenti.
Ecco alcune modifiche che suggerirei
• Scorri automaticamente nel riquadro a sinistra fino alla sezione attualmente attiva sui documenti principali. Questa opzione può essere utile per tenere traccia delle sezioni attuali, future e passate. • Copia negli appunti: alcuni comandi possono richiedere molto tempo. 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 in modo corretto, ad esempio la sezione Resource Type (Tipo di risorsa) nella panoramica di kubectl. Ciò influisce negativamente sull'esperienza utente.
Queste sono le modifiche che possono migliorare l'esperienza utente sul sito web Kubernetes e possono anche aumentare la produttività degli utenti.