Le seguenti linee guida ti aiuteranno a presentare i tuoi contenuti sotto forma di tutorial in modo che gli utenti possano acquisire familiarità con il tuo progetto.
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 Precedente in ogni passaggio. Possono anche chiudere il tutorial e riprendere da dove avevano interrotto.
- Codice da usare ovunque: 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 passare da una pagina all'altra 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: usa i pronomi di seconda persona (da usare: tu, tuo; da non usare: 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 specifici: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 scoprirai come creare un nuovo tutorial. | Continua con il passaggio successivo per iniziare a configurare il tutorial. | Concentrati sull'utente; utilizzo della forma attiva
Uso di un linguaggio informale |
| Esegui questo comando:
``` gcloud projects list --format="table[box,title=Projects](name, projectId)" ``` |
Per visualizzare un elenco in tabella di tutti i tuoi progetti e dei relativi numeri ID, denominato "Progetti", esegui il seguente comando: ``` gcloud projects list --format="table[box,title=Projects](name, projectId)" ``` | Spiegazione del ragionamento in anticipo per impostare le aspettative relative all'output |
Let's get started!
|
Let's get started!
Questa guida ti mostrerà come creare il tuo tutorial interattivo. Inoltre, ti guiderà nella generazione di un pulsante che gli utenti possono utilizzare per avviare il tutorial completato. |
Una roadmap chiara delle lezioni trattate nel tutorial
Assicurati di mantenere questo obiettivo quando scrivi i contenuti. |
Best practice
Mantieni brevi i tutorial: i vincoli di spazio unici del riquadro del tutorial fanno sì che sia possibile presentare a un utente una quantità limitata di informazioni alla volta. Evita blocchi di testo di grandi dimensioni che sono difficili da esaminare e richiedono lo scorrimento verticale; prediligi le informazioni presentate in blocchi di piccole dimensioni.
Non dovresti superare i 5 passaggi e i 3 snippet di codice per pagina.
Idealmente, i paragrafi devono essere composti da massimo 5 righe e trattare un unico concetto.
Se una pagina deve essere lunga, cerca di non superare il doppio della lunghezza del riquadro.
Il codice e i blocchi di terminali devono essere sufficientemente piccoli da poter essere letti:
- Cerca di non superare le 10 righe.
- Cerca di utilizzare al massimo 80 caratteri per riga per ridurre lo scorrimento orizzontale.
- Evita blocchi di codice con più comandi per impedire agli utenti di dover eseguire un'operazione di copia ed esecuzione collettiva.
Pagina introduttiva: inizia il tutorial con un'introduzione.
- Stabilisci 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 impiegare per il 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 testo fitto), ti consigliamo di suddividerlo in una serie di tutorial più brevi.
- Di' subito: indica chiaramente le risorse o gli accessi di cui gli utenti potrebbero dover disporre per completare il tutorial senza interruzioni.
Esempio ## Iniziamo.
Aiutano gli utenti a iniziare a utilizzare rapidamente il progetto includendo un tutorial interattivo.
Questa guida ti mostrerà come creare il tuo tutorial interattivo (come questo). Inoltre, ti guiderà 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 il contesto: quando scrivi un tutorial, spesso è utile fornire il contesto. Ad esempio, potresti fornire una breve panoramica del prodotto o illustrare rapidamente le funzionalità salienti di un'interfaccia utente.
Esempio ## Che cos'è Cloud Shell?
Prima di iniziare, vediamo brevemente cosa può fare Cloud Shell.
Cloud Shell è una macchina virtuale ospitata personalmente su cui sono preinstallati gli strumenti per sviluppatori per i prodotti Google Cloud. Questo ambiente shell interattivo è dotato di un editor di codice integrato, dello spazio di archiviazione su disco permanente e della funzionalità di anteprima web. Per utilizzare solo l'accesso a 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 eseguire un caso d'uso e familiarizzare con le funzionalità del progetto.
Vai al passaggio successivo per iniziare a configurare il tutorial.
Esempi di base:
- Un semplice "Hello World": il primo esempio fornito deve essere sufficientemente semplice da poter essere testato dall'utente senza troppe spiegazioni. Deve essere equivalente a Hello World. Utilizza questo esempio come base per continuare a sviluppare i concetti nel corso del 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. Avere il tutorial e l'ambiente di sviluppo aperti nello stesso posto semplifica per gli utenti l'inizio dell'utilizzo del progetto tramite un'esperienza semplice su un'unica schermata.
Prova a eseguire un comando:
```bash
echo "Un saluto da Cloud Shell"
```
**Suggerimento**: fai clic sul pulsante Copia accanto alla casella del codice per incollare il comando nel terminale Cloud Shell ed eseguirlo.
A questo punto, scriverai e lancerai un tutorial di base.
Contenuti del tutorial
- Utilizza la formattazione con cautela:la formattazione del testo (grassetto, corsivo e così via) è fonte di distrazione. Utilizzala solo se necessario e a tuo vantaggio (per avvisi, informazioni chiave e così via).
- Grammatica coerente: utilizza il modo imperativo per descrivere l'azione dell'utente e assicurati di terminare le frasi con un punto.
- Riferimento ai link: se essenziali per il contesto, includi link supplementari ([link text](link URL)) in modo che gli utenti possano fare le proprie ricerche.
- Scegli l'evidenziazione anziché gli screenshot: l'evidenziazione è un'azione che consente di mettere in evidenza la posizione degli elementi dell'interfaccia utente nella console Google Cloud, in modo che gli utenti possano identificarli senza dover cercare un'immagine.
- Visualizzazione alternativa: se possibile, fornisci un link ai contenuti del tutorial offerti come contenuti statici; in questo modo gli utenti avranno la libertà di scegliere come fruire delle informazioni fornite.
- Suggerimenti apprezzati: se opportuno, aggiungi suggerimenti (contrassegnati da "**Suggerimento:**") per fornire agli utenti soluzioni e best practice più intuitive.
Esempio ## Scrivere in Markdown
Per scrivere il tutorial, utilizza [Markdown](https://it.wikipedia.org/wiki/Markdown) e segui queste linee guida:
### Modificare il titolo
Modifica il titolo di questo tutorial ("# Introduzione alla scrittura di tutorial in Cloud Shell") in:
```
# Teach me to write a tutorial
```
### Aggiungere un nuovo passaggio
Aggiungi un passaggio subito dopo il titolo, ad esempio:
```
## Passaggio 1
Questo è un nuovo passaggio che ho appena aggiunto.
```
Ogni "passaggio" di un tutorial viene visualizzato in una pagina.
**Suggerimento**: per spostarsi tra i passaggi, gli utenti utilizzeranno i pulsanti "Indietro" e 'Continua/Avanti".
Riepilogo
- Congratulazioni: assicurati di aggiungere un'icona del trofeo (<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>) per ringraziare gli utenti che si sono presi il tempo di completare il tutorial.
- Conclusione: riepiloga le lezioni importanti che vuoi che gli utenti acquisiscano dal tutorial.
- Passaggio successivo: aiuta gli utenti nel loro percorso fornendo i passaggi successivi, ad esempio letture consigliate, risorse supplementari o persino un altro tutorial.
- Prendi cura dei tuoi utenti: consiglia loro di eliminare le risorse di test che hanno creato ai fini del tutorial per evitare addebiti indesiderati.
Esempio ## Congratulazioni
<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>
Ecco fatto.
Ora puoi chiedere agli utenti di avviare il tutorial in Cloud Shell e iniziare a utilizzare il tuo progetto con facilità.
Per un elenco completo degli strumenti per la scrittura dei tutorial di Cloud Shell, consulta il [riferimento Markdown per i tutorial](https://cloud.google.com/shell/docs/tutorial-markdown-reference).
**Non dimenticare di eseguire la pulizia**: se hai creato progetti di test, assicurati di eliminarli per evitare addebiti non necessari. Utilizza `gcloud projects delete <PROJECT-ID>`.