Le seguenti linee guida ti aiuteranno a presentare i tuoi contenuti sotto forma di tutorial, in modo che gli utenti possano familiarizzare efficacemente con il tuo progetto.
Funzionalità di Cloud Shell
- Layout univoco: i tutorial sono presentati in un riquadro laterale sul lato destro della console Google Cloud.
- Navigazione: gli utenti possono spostarsi nel tutorial utilizzando i pulsanti Avanti e Indietro in ogni passaggio. Possono anche chiudere il tutorial e riprendere da dove l'avevano interrotto.
- Codice da utilizzare: gli snippet di codice possono essere copiati direttamente in Cloud Shell.
Sessione dell'editor di Cloud Shell con un riquadro tutorial aperto. Gli utenti possono copiare il codice direttamente in Cloud Shell facendo clic su un pulsante e passare da una pagina all'altra con i pulsanti Avanti e Indietro.
Stile di scrittura
- Sii chiaro: i tutorial devono essere informativi e utili dal tono, ma non eccessivamente formali.
- Tu, l'utente: usa pronomi di seconda persona (utilizza: tu, il tuo; non usare: noi, io, il nostro e così via)
- Spiega causa ed effetto: quando chiedi agli utenti di eseguire un passaggio, spiega il ragionamento alla base dell'azione e il risultato previsto.
- Avere obiettivi mirati: prima di scrivere i contenuti per il tutorial, stabilisci un obiettivo ben definito che vuoi far raggiungere agli utenti. Realizza il tuo tutorial tenendo presente questo obiettivo.
| Originale | Rivisto | Miglioramento |
| Nella pagina successiva, imparerai come creare un nuovo tutorial. | Continua con il passaggio successivo per iniziare la configurazione del tutorial. | Concentrazione sull'utente; uso della forma attiva
Uso di un linguaggio rilassato |
| Esegui questo comando:
``` gcloud projects list --format="table[box,title=Projects](name, projectId)" ``` |
Per visualizzare un elenco tabulare di tutti i progetti con i relativi numeri ID, dal titolo "Projects", esegui questo comando: ``` gcloud projects list --format="table[box,title=Projects](name, projectId)" ``` | Spiegazione del ragionamento iniziale per definire le aspettative relative all'output |
Let's get started!
|
Let's get started!
Questa guida ti mostrerà come creare il tuo tutorial interattivo. Ti verrà inoltre spiegato come generare un pulsante che gli utenti possono utilizzare per avviare il tutorial completato. |
Una roadmap chiara delle lezioni trattate nel tutorial
Concentrati su questo argomento quando scrivi contenuti. |
best practice
Sii breve: i limiti di spazio univoci del riquadro del tutorial fanno sì che a un utente possa essere presentata una quantità limitata di informazioni alla volta. Evita porzioni di testo di grandi dimensioni difficili da leggere e che richiedono lo scorrimento verticale; prediligi le informazioni presentate in porzioni di dimensioni ridotte.
Cerca di non superare i cinque passaggi e i tre snippet di codice per pagina.
Idealmente, i paragrafi dovrebbero essere di massimo 5 righe e trattare un concetto unico.
Se una pagina deve essere lunga, cerca di fare in modo che superi al massimo il doppio della lunghezza del riquadro.
Il codice e le morsettiere devono essere sufficientemente piccoli da poter leggere:
- Mira a 10 righe o meno.
- Cerca di non superare gli 80 caratteri per riga per ridurre lo scorrimento orizzontale.
- Evita blocchi di codice con più comandi per impedire agli utenti di eseguire una copia collettiva.
Pagina introduttiva: inizia il tutorial con un'introduzione.
- Definisci le aspettative: spiega brevemente in che modo i tuoi utenti traggono profitto dal completamento di questo tutorial.
- Impegno di tempo stimato: stima approssimativamente il tempo che gli utenti possono aspettarsi di dedicare al tutorial. Cerca di creare un tutorial che possa essere completato in meno di 15 minuti. Se il tutorial è più lungo (o è composto da più di 15 pagine con più parole), valuta la possibilità di suddividerlo in una serie di tutorial più piccoli.
- Sii chiaro: indica chiaramente eventuali risorse o accessi dei prerequisiti che gli utenti potrebbero dover configurare per svolgere il tutorial senza interruzioni.
Esempio ## Iniziamo.
Rendi rapidamente operativi gli utenti con il tuo progetto includendo un tutorial interattivo.
Questa guida ti mostrerà come creare il tuo tutorial interattivo (come questo). Ti verrà inoltre spiegato come generare un pulsante che gli utenti possono usare per avviare il tutorial completato.
**Tempo di completamento**: circa 10 minuti
**Prerequisiti**: un account di fatturazione Cloud
Fai clic sul pulsante **Continua** per procedere con il passaggio successivo.
Pagina di sfondo
- Prepara la scena: spesso è utile fornire un contesto durante la scrittura di un tutorial. Potrebbe essere necessario fornire una breve panoramica del prodotto o esaminare rapidamente le caratteristiche salienti di una UI.
Esempio ## Che cos'è Cloud Shell?
Prima di iniziare, vediamo brevemente cosa può fare Cloud Shell.
Cloud Shell è una macchina virtuale ospitata personale in cui sono precaricati strumenti per sviluppatori per i prodotti Google Cloud. Questo ambiente shell interattivo include un editor di codice integrato, l'archiviazione su disco permanente e una funzionalità di anteprima web. Per utilizzare l'accesso da riga di comando da solo, visita [console.cloud.google.com/cloudshell](https://console.cloud.google.com/cloudshell).
Puoi indirizzare gli utenti a Cloud Shell per aiutarli a iniziare rapidamente con il tuo progetto, offrendo loro l'opportunità di esaminare un caso d'uso e acquisire familiarità con le funzionalità del progetto.
Vai al passaggio successivo per iniziare a configurare il tutorial.
Esempi di base:
- Hello World: il primo esempio fornito deve essere abbastanza semplice da consentire all'utente di eseguire il test senza molte spiegazioni. Dovrebbe essere l'equivalente di Hello World. Utilizza questo esempio come base per continuare a creare esemplificazioni per i concetti durante il tutorial.
Esempio ## Tutorial contestualizzati
Quello che stai guardando ora è un tutorial contestuale.
I contenuti vengono visualizzati insieme all'ambiente Cloud Shell in cui puoi eseguire i passaggi del tutorial. Se il tutorial e l'ambiente di sviluppo sono aperti nella stessa posizione, per gli utenti sarà più facile iniziare a utilizzare il progetto mediante una semplice esperienza su schermo singolo.
Prova a eseguire un comando ora:
'``bash
echo "Ciao Cloud Shell"
```
**Suggerimento**: fai clic sul pulsante Copia sul lato della casella del codice per incollare il comando nel terminale Cloud Shell ed eseguirlo.
Successivamente, scriverai e avvierai un tutorial di base.
Contenuti del tutorial
- Utilizza il formato con cautela: la formattazione del testo (grassetto, corsivo e così via) disturba; utilizzala solo quando necessario e a tuo vantaggio (per avvisi, informazioni chiave e così via).
- Grammatica coerente: usa il tempo imperativo quando descrivi l'azione dell'utente e assicurati di terminare le frasi con un punto.
- Fai riferimento ai link: se è essenziale per contesto, includi link supplementari ([testo del link](URL del link)) in modo che gli utenti possano effettuare le proprie ricerche.
- Scegli l'evidenziazione anziché gli screenshot:l'attività in evidenza, un'azione che evidenzia dove si trovano gli elementi UI nella console Google Cloud, ne mostra la posizione in modo che gli utenti possano identificare gli elementi senza cercare un'immagine.
- Visualizzazione alternativa: se possibile, fornisci un link ai contenuti dei tutorial offerti come contenuti statici, in modo che gli utenti possano scegliere in che modo consumare le informazioni fornite.
- Suggerimenti apprezzati: ove possibile, aggiungi dei suggerimenti (con "**Tip:**") per offrire agli utenti soluzioni e best practice più intuitive.
Esempio ## Scrittura in Markdown
Per scrivere il tutorial, utilizza [Markdown](https://en.wikipedia.org/wiki/Markdown) e segui queste linee guida:
### Modifica il titolo
Modifica il titolo di questo tutorial ("# Introduzione alla scrittura di tutorial in Cloud Shell") modificandolo in:
```
# Insegnami a scrivere un tutorial
```
### Aggiungere un nuovo passaggio
Quindi, aggiungi un passaggio subito dopo il titolo, in questo modo:
```
## Passaggio 1
Questo è un nuovo passaggio che ho appena aggiunto.
```
Ogni "passaggio" di un tutorial viene visualizzato in un'unica pagina.
**Suggerimento**: per spostarti tra i passaggi, gli utenti utilizzeranno i pulsanti "Indietro" e "Continua/Avanti".
Riepilogo
- Congratulazioni: assicurati di aggiungere un'icona trofeo (<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>) per apprezzare gli utenti che hanno dedicato del tempo a completare il tutorial.
- Conclusione: riassumi le lezioni importanti che vorresti che gli utenti avessero appreso dal tutorial.
- Passaggi successivi: aiuta gli utenti nel loro percorso fornendo i passaggi successivi, che potrebbero essere letture consigliate, risorse supplementari o persino un altro tutorial.
- Cerca i tuoi utenti: consiglia loro di ripulire le risorse di test che hanno creato ai fini del tutorial per evitare addebiti indesiderati.
Esempio ## Complimenti
<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>
Ecco fatto.
Ora puoi consentire agli utenti di avviare il tuo tutorial in Cloud Shell per iniziare a utilizzare facilmente il tuo progetto.
Per un elenco completo degli strumenti di scrittura dei tutorial di Cloud Shell, consulta la [guida di riferimento di Markdown del tutorial](https://cloud.google.com/shell/docs/tutorial-markdown-reference).
**Non dimenticare di eseguire la pulizia dopo te stesso**: se hai creato progetti di test, assicurati di eliminarli per evitare addebiti inutili. Utilizza "gcloud projects delete <PROJECT-ID>".