Panduan berikut akan membantu Anda menyajikan konten dalam bentuk tutorial sehingga pengguna dapat memahami project Anda secara efektif.
Fitur Cloud Shell
- Tata letak unik: Tutorial ditampilkan di panel samping di sisi kanan konsol Google Cloud.
- Navigasi: Pengguna dapat melanjutkan tutorial menggunakan tombol Berikutnya dan Sebelumnya di setiap langkah. Pengguna juga dapat menutup tutorial dan melanjutkan dari bagian yang terakhir dilihat.
- Kode untuk dibawa: Cuplikan kode dapat disalin langsung ke Cloud Shell.
Sesi Cloud Shell Editor dengan panel tutorial terbuka. Pengguna dapat menyalin kode langsung ke Cloud Shell dengan mengklik tombol, dan dapat berpindah antar- halaman dengan tombol Berikutnya dan Sebelumnya.
Gaya penulisan
- Ringan-ringan saja: Tutorial harus informatif dan bermanfaat, tetapi tidak terlalu formal.
- Anda, pengguna: Gunakan kata ganti orang kedua (gunakan: Anda, milik Anda; jangan gunakan: kami, saya, milik kami, dan sebagainya)
- Jelaskan sebab dan akibat: Saat meminta pengguna untuk melakukan langkah, jelaskan alasan di balik tindakan tersebut dan hasil yang diharapkan.
- Memiliki sasaran yang terfokus: Sebelum menulis konten untuk tutorial, tentukan sasaran yang jelas yang ingin dicapai pengguna. Buat tutorial Anda dengan mempertimbangkan sasaran ini.
| Asli | Direvisi | Peningkatan |
| Di halaman berikutnya, Anda akan mempelajari cara membuat tutorial baru. | Lanjutkan ke langkah berikutnya untuk mulai menyiapkan tutorial Anda. | Fokus pada pengguna; penggunaan kalimat aktif
Penggunaan bahasa yang santai |
| Jalankan perintah ini:
``` gcloud projects list --format="table[box,title=Projects](name, projectId)" ``` |
Untuk menampilkan daftar tabel semua project dan nomor ID-nya, yang berjudul 'Project', jalankan perintah berikut: ``` gcloud projects list --format="table[box,title=Projects](name, projectId)" ``` | Penjelasan alasan di awal untuk menetapkan ekspektasi tentang output |
Let's get started!
|
Let's get started!
Panduan ini akan menunjukkan cara mem-build tutorial interaktif Anda sendiri. Tutorial ini juga akan memandu Anda membuat tombol yang dapat digunakan pengguna untuk meluncurkan tutorial yang sudah selesai. |
Jelas roadmap pelajaran yang dibahas dalam tutorial
Pastikan untuk mempertahankan fokus ini saat menulis konten. |
Praktik terbaik
Panjangnya tidak boleh terlalu banyak: Batasan ruang unik pada panel tutorial berarti jumlah informasi yang dapat ditampilkan kepada pengguna dalam satu waktu terbatas. Hindari potongan teks besar yang sulit dipindai dan memerlukan scroll vertikal; pilih informasi yang disajikan dalam potongan kecil.
Usahakan tidak lebih dari 5 langkah dan 3 cuplikan kode per halaman.
Idealnya, paragraf terdiri dari 5 baris atau kurang dan harus membahas konsep tunggal.
Jika halaman harus panjang, usahakan panjangnya maksimal dua kali panjang panel.
Blok kode dan terminal harus cukup kecil untuk dibaca:
- Usahakan 10 baris atau kurang.
- Usahakan 80 karakter atau kurang per baris, untuk mengurangi scrolling horisontal.
- Hindari blok kode multi-perintah untuk mencegah pengguna harus melakukan eksekusi salinan massal.
Halaman pengantar: Mulai tutorial Anda dengan pengantar.
- Tetapkan ekspektasi: Jelaskan secara singkat bagaimana pengguna akan mendapatkan manfaat dari menyelesaikan tutorial ini.
- Perkiraan komitmen waktu: Perkiraan waktu yang akan dihabiskan pengguna untuk tutorial. Usahakan untuk membuat tutorial yang dapat diselesaikan dalam waktu kurang dari 15 menit. Jika tutorial Anda lebih panjang (atau terdiri dari lebih dari 15 halaman yang padat kata), pertimbangkan untuk membaginya menjadi serangkaian tutorial yang lebih kecil.
- Beri tahu pengguna sejak awal: Nyatakan dengan jelas semua akses atau referensi prasyarat yang mungkin perlu disiapkan pengguna agar dapat mengikuti tutorial tanpa gangguan.
Contoh ## Mari kita mulai.
Siapkan dan jalankan project Anda dengan cepat dengan menyertakan tutorial interaktif.
Panduan ini akan menunjukkan cara membuat tutorial interaktif Anda sendiri (seperti ini). Tutorial ini juga akan memandu Anda membuat tombol yang dapat digunakan pengguna untuk meluncurkan tutorial yang sudah selesai.
**Waktu yang diperlukan**: Sekitar 10 menit
**Prasyarat**: Akun Penagihan Cloud
Klik tombol **Lanjutkan** untuk melanjutkan ke langkah berikutnya.
Halaman latar belakang
- Buat latar belakang: Saat menulis tutorial, sebaiknya beri konteks. Hal ini mungkin berarti memberikan ringkasan singkat tentang produk atau menjalankan fitur penting UI dengan cepat.
Contoh ## Apa itu Cloud Shell?
Sebelum memulai, mari kita bahas secara singkat apa saja yang dapat dilakukan Cloud Shell.
Cloud Shell adalah Virtual Machine yang dihosting secara pribadi dan sudah dimuat sebelumnya dengan alat developer untuk produk Google Cloud. Lingkungan shell interaktif ini dilengkapi dengan editor kode bawaan, penyimpanan disk persisten, dan fungsi pratinjau web. Untuk menggunakan akses command line saja, buka [console.cloud.google.com/cloudshell](https://console.cloud.google.com/cloudshell).
Anda dapat mengarahkan pengguna ke Cloud Shell untuk membantu mereka memulai project dengan cepat; memberi mereka kesempatan untuk mempelajari kasus penggunaan dan memahami fungsi project Anda.
Lanjutkan ke langkah berikutnya untuk mulai menyiapkan tutorial.
Contoh Dasar:
- Hello World: Contoh pertama yang Anda berikan harus cukup sederhana untuk diuji pengguna tanpa banyak penjelasan. Ini harus setara dengan Hello World Anda. Gunakan contoh ini sebagai dasar untuk terus membangun contoh konsep melalui tutorial.
Contoh ## Tutorial dalam konteks
Yang Anda lihat sekarang adalah tutorial dalam konteks.
Konten ditampilkan bersama dengan lingkungan Cloud Shell tempat Anda dapat melakukan langkah-langkah tutorial. Dengan membuka tutorial dan lingkungan pengembangan di tempat yang sama, pengguna akan lebih mudah untuk mulai menggunakan project Anda melalui pengalaman layar tunggal yang mudah.
Coba jalankan perintah sekarang:
```bash
echo "Hello Cloud Shell"
```
**Tips**: Klik tombol salin di samping kotak kode untuk menempelkan perintah di terminal Cloud Shell guna menjalankannya.
Selanjutnya, Anda akan menulis dan meluncurkan tutorial dasar.
Konten Tutorial
- Format dengan hati-hati: Pemformatan teks (tebal, miring, dll.) akan mengganggu; gunakan hanya jika diperlukan dan untuk keuntungan Anda (untuk peringatan, pembelajaran utama, dll.).
- Tata bahasa yang konsisten: Gunakan bentuk imperatif saat mendeskripsikan tindakan pengguna dan pastikan untuk mengakhiri kalimat dengan titik.
- Merujuk ke link: Jika diperlukan untuk konteks, sertakan link tambahan ([link text](link URL)) agar pengguna dapat melakukan riset mereka sendiri.
- Pilih sorotan, bukan screenshot: Sorotan, tindakan yang menandai lokasi elemen UI di konsol Google Cloud, menunjukkan posisi sehingga pengguna dapat mengidentifikasi elemen tanpa menelusuri gambar.
- Tampilan alternatif: Jika memungkinkan, berikan link ke konten tutorial Anda yang ditawarkan sebagai konten statis; hal ini memberi pengguna kebebasan untuk memilih cara mereka ingin menggunakan informasi yang diberikan.
- Tips dihargai: Jika berlaku, tambahkan tips (ditandai dengan "**Tips:**") untuk memberi pengguna solusi dan praktik terbaik yang lebih intuitif.
Contoh ## Menulis dalam Markdown
Untuk menulis tutorial, gunakan [Markdown](https://en.wikipedia.org/wiki/Markdown) dan ikuti panduan berikut:
### Mengedit judul
Ubah judul tutorial ini ('# Pengantar penulisan tutorial di Cloud Shell') dengan mengubahnya menjadi:
```
# Ajari saya cara menulis tutorial
```
### Menambahkan langkah baru
Selanjutnya, tambahkan langkah tepat setelah judul seperti ini:
```
## Langkah 1
Ini adalah langkah baru yang baru saja saya tambahkan.
```
Setiap 'langkah' tutorial ditampilkan di satu halaman.
**Tips**: Untuk berpindah antarlangkah, pengguna akan menggunakan tombol 'Kembali' dan 'Lanjutkan/Maju'.
Ringkasan
- Selamat: Pastikan untuk menambahkan ikon piala (<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>) untuk mengapresiasi pengguna yang meluangkan waktu untuk menyelesaikan tutorial.
- Penutup: Ringkas pelajaran penting yang ingin Anda sampaikan kepada pengguna dari tutorial.
- Langkah berikutnya: Bantu pengguna di sepanjang perjalanan mereka dengan memberikan langkah-langkah berikutnya - ini dapat berupa bacaan yang direkomendasikan, referensi tambahan, atau bahkan tutorial lain.
- Jaga pengguna Anda: Sarankan mereka untuk menghapus resource pengujian apa pun yang mereka buat untuk tujuan tutorial guna menghindari tagihan penagihan yang tidak diinginkan.
Contoh ## Selamat
<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>
Anda sudah siap!
Sekarang Anda dapat meminta pengguna untuk meluncurkan tutorial di Cloud Shell dan mulai menggunakan project Anda dengan mudah.
Untuk mengetahui daftar lengkap alat penulisan tutorial Cloud Shell, lihat [Referensi Markdown Tutorial](https://cloud.google.com/shell/docs/tutorial-markdown-reference).
**Jangan lupa untuk membersihkan project Anda**: Jika Anda membuat project pengujian, pastikan untuk menghapusnya agar terhindar dari tagihan yang tidak perlu. Gunakan `gcloud projects delete <PROJECT-ID>`.