Le seguenti linee guida ti aiuteranno a presentare i tuoi contenuti sotto forma di tutorial in modo che i tuoi utenti possano acquisire familiarità con il tuo progetto in modo efficace.
Funzionalità di Cloud Shell
- Layout unico: i tutorial vengono 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 avevano interrotto.
- Codice da usare: gli snippet di codice possono essere copiati direttamente in Cloud Shell.
Una sessione dell'editor di Cloud Shell con un riquadro del tutorial aperto. Gli utenti possono copiare il codice direttamente in Cloud Shell facendo clic su un pulsante e possono spostarsi tra le pagine con i pulsanti Avanti e Indietro.
Stile di scrittura
- Mantieni un tono leggero: i tutorial devono essere informativi e utili, ma non eccessivamente formali.
- Tu, l'utente:utilizza i pronomi di seconda persona (utilizza: tu, tuo, i tuoi; non utilizzare: noi, io, nostro e così via)
- Spiega la causa e l'effetto: quando chiedi agli utenti di eseguire un passaggio, spiega il ragionamento alla base dell'azione e il risultato previsto.
- Definisci obiettivi mirati:prima di scrivere i contenuti del tutorial, stabilisci un obiettivo ben definito che vuoi che i tuoi utenti raggiungano. Crea il tuo tutorial tenendo presente questo obiettivo.
| Originale | Rivisto | Miglioramento |
| Nella pagina successiva, imparerai a creare un nuovo tutorial. | Fai clic su Continua per passare al passaggio successivo e iniziare a configurare il tutorial. | Concentrati sull'utente; usa la forma attiva
Uso di un linguaggio informale |
| Esegui questo comando:
``` gcloud projects list --format="table[box,title=Projects](name, projectId)" ``` |
Per visualizzare un elenco tabellare di tutti i tuoi progetti e dei relativi numeri ID, intitolato "Projects", esegui questo comando: ``` gcloud projects list --format="table[box,title=Projects](name, projectId)" ``` | Spiegazione del ragionamento iniziale per stabilire le aspettative sull'output |
Let's get started!
|
Let's get started!
Questa guida ti mostrerà come creare il tuo tutorial interattivo. Ti guiderà anche nella generazione di un pulsante che gli utenti possono utilizzare per avviare il tutorial completato. |
Roadmap chiara delle lezioni trattate nel tutorial
Assicurati di mantenere questo focus quando scrivi i contenuti. |
Best practice
Sii breve:i limiti di spazio del riquadro del tutorial consentono di presentare agli utenti solo una quantità limitata di informazioni alla volta. Evita blocchi di testo di grandi dimensioni difficili da scorrere e che richiedono lo scorrimento verticale; preferisci informazioni presentate in blocchi più piccoli.
Cerca di non superare i 5 passaggi e i 3 snippet di codice per pagina.
Idealmente, i paragrafi dovrebbero essere composti da un massimo di 5 righe e trattare un singolo concetto.
Se una pagina deve essere lunga, cerca di farla essere al massimo il doppio della lunghezza del riquadro.
I blocchi di codice e terminali devono essere abbastanza piccoli da essere letti:
- Cerca di non superare le 10 righe.
- Cerca di utilizzare un massimo di 80 caratteri per riga per ridurre lo scorrimento orizzontale.
- Evita i blocchi di codice multi-comando per impedire agli utenti di dover eseguire una copia ed esecuzione collettiva.
Pagina introduttiva:inizia il tutorial con un'introduzione.
- Definisci le aspettative:spiega brevemente in che modo gli utenti trarranno vantaggio dal completamento di questo tutorial.
- Tempo stimato: stima approssimativa del tempo che gli utenti possono prevedere di dedicare al tutorial. Cerca di creare un tutorial che possa essere completato in meno di 15 minuti. Se il tuo tutorial è più lungo (o è composto da più di 15 pagine con un testo denso), valuta la possibilità di suddividerlo in una serie di tutorial più brevi.
- Sii chiaro:indica chiaramente le risorse o l'accesso prerequisiti che gli utenti potrebbero dover configurare per seguire il tutorial senza interruzioni.
Esempio ## Iniziamo.
Rendi velocemente operativi gli utenti con il tuo progetto includendo un tutorial interattivo.
Questa guida ti mostrerà come creare un tutorial interattivo personalizzato (come questo). Ti guiderà anche nella generazione di un pulsante che gli utenti possono utilizzare per avviare il tutorial completato.
**Tempo di completamento**: circa 10 minuti
**Prerequisiti**: un account di fatturazione Cloud
Fai clic sul pulsante **Continua** per passare al passaggio successivo.
Pagina di sfondo
- Crea la scena:quando scrivi un tutorial, spesso è utile fornire un contesto. Ciò potrebbe significare fornire una breve panoramica del prodotto o illustrare rapidamente le funzionalità principali di una UI.
Esempio ## Che cos'è Cloud Shell?
Prima di iniziare, vediamo brevemente cosa può fare Cloud Shell.
Cloud Shell è una macchina virtuale personale ospitata su cui sono precaricati strumenti per sviluppatori per i prodotti Google Cloud . Questo ambiente shell interattivo è dotato di un editor di codice integrato, spazio di archiviazione su disco permanente e funzionalità di anteprima web. Per utilizzare solo l'accesso alla riga di comando, visita la pagina [console.cloud.google.com/cloudshell](https://console.cloud.google.com/cloudshell).
Puoi indirizzare gli utenti a Cloud Shell per aiutarli a iniziare rapidamente a utilizzare il tuo progetto, offrendo loro l'opportunità di esaminare un caso d'uso e familiarizzare con le funzionalità del progetto.
Continua con il passaggio successivo per iniziare a configurare il tutorial.
Esempi di base:
- Hello World: il primo esempio che fornisci deve essere abbastanza semplice da consentire all'utente di testarlo senza molte spiegazioni. Deve essere l'equivalente di Hello World. Utilizza questo esempio come base per continuare a sviluppare concetti durante il tutorial.
Esempio ## Tutorial contestuali
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 l'ambiente di sviluppo e il tutorial sono aperti nello stesso posto, gli utenti possono iniziare a utilizzare il progetto più facilmente grazie a un'esperienza semplice su un'unica schermata.
Prova a eseguire un comando ora:
```bash
echo "Hello Cloud Shell"
```
**Suggerimento**: fai clic sul pulsante Copia accanto alla casella del codice per incollare il comando nel terminale Cloud Shell ed eseguirlo.
Poi scriverai e lancerai un tutorial di base.
Contenuti del tutorial
- Formatta con cautela:la formattazione del testo (grassetto, corsivo e così via) distrae; utilizzala solo quando necessario e a tuo vantaggio (per avvisi, apprendimenti chiave e così via).
- Grammatica coerente:utilizza il modo imperativo quando descrivi l'azione dell'utente e assicurati di terminare le frasi con un punto.
- Fai riferimento ai link:se essenziali per il contesto, includi link supplementari ([testo del link](URL del link)) in modo che gli utenti possano fare le proprie ricerche.
- Scegli l'evidenziazione anziché gli screenshot: l'evidenziazione, un'azione che mette in evidenza la posizione degli elementi dell'interfaccia utente nella console Google Cloud , 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 del tutorial offerti come contenuti statici. In questo modo, gli utenti possono scegliere come consumare le informazioni fornite.
- Suggerimenti apprezzati: se applicabile, aggiungi suggerimenti (indicati da "**Suggerimento:**") per fornire agli utenti soluzioni e best practice più intuitive.
Esempio ## Scrivere 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 ("# Introduction to writing tutorials in Cloud Shell") modificandolo in:
```
# Teach me to write a tutorial
```
### Aggiungere un nuovo passaggio
A questo punto, aggiungi un passaggio subito dopo il titolo:
```
## Passaggio 1
Questo è un nuovo passaggio che ho appena aggiunto.
```
Ogni "passaggio" di un tutorial viene visualizzato su una pagina.
**Suggerimento**: per spostarsi tra i passaggi, gli utenti utilizzeranno i pulsanti "Indietro" e "Continua/Avanti".
Riepilogo
- Congratulazioni: assicurati di aggiungere un'icona a forma di trofeo (<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>) per ringraziare gli utenti che hanno dedicato del tempo a completare il tutorial.
- Riepilogo:riassumi le lezioni importanti che vuoi che gli utenti imparino dal tutorial.
- Passaggi successivi:aiuta gli utenti nel loro percorso fornendo i passaggi successivi. Potrebbero essere letture consigliate, risorse supplementari o anche un altro tutorial.
- Attenzione agli utenti: consiglia loro di eliminare le risorse di test che hanno creato per il tutorial per evitare addebiti indesiderati.
Esempio ## Congratulazioni
<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>
Ecco fatto.
Ora gli utenti possono avviare il tutorial in Cloud Shell e iniziare a utilizzare il tuo progetto con facilità.
Per un elenco completo degli strumenti di scrittura dei tutorial di Cloud Shell, consulta la [Guida di riferimento a Markdown per i tutorial](https://cloud.google.com/shell/docs/tutorial-markdown-reference).
**Non dimenticare di fare pulizia**: se hai creato progetti di test, assicurati di eliminarli per evitare addebiti non necessari. Utilizza `gcloud projects delete <PROJECT-ID>`.