Panduan berikut akan membantu Anda menyajikan konten dalam bentuk tutorial sehingga pengguna dapat memahami proyek Anda secara efektif.
Fitur Cloud Shell
- Tata letak unik: Tutorial ditampilkan di panel samping di sisi kanan konsol Google Cloud .
- Navigasi: Pengguna dapat berpindah-pindah dalam tutorial menggunakan tombol Berikutnya dan Sebelumnya di setiap langkah. Pengguna juga dapat menutup tutorial dan melanjutkan dari bagian terakhir yang mereka buka.
- Kode untuk digunakan: 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 antarhalaman dengan tombol Berikutnya dan Sebelumnya.
Gaya penulisan
- Buat suasana santai: Tutorial harus informatif dan bermanfaat, tetapi tidak terlalu formal.
- Anda, pengguna: Gunakan kata ganti orang kedua (gunakan: Anda, milik Anda; jangan gunakan: kami, saya, kami, dan sebagainya)
- Jelaskan sebab dan akibat: Saat meminta pengguna melakukan langkah-langkah, jelaskan alasan di balik tindakan dan hasil yang diharapkan.
- Memiliki tujuan yang terfokus: Sebelum menulis konten untuk tutorial, tetapkan tujuan yang jelas yang ingin Anda capai oleh pengguna. Buat tutorial 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. | Berfokus 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 semua project Anda dan nomor ID-nya dalam bentuk tabel, berjudul 'Projects', 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 kepada Anda cara membuat tutorial interaktif Anda sendiri. Anda juga akan mempelajari cara membuat tombol yang dapat digunakan pengguna untuk meluncurkan tutorial yang telah selesai. |
Roadmap yang jelas tentang pelajaran yang dibahas dalam tutorial
Pastikan untuk mempertahankan fokus ini saat menulis konten. |
Praktik terbaik
Singkat: Batasan ruang unik pada panel tutorial berarti hanya sejumlah kecil informasi yang dapat ditampilkan kepada pengguna dalam satu waktu. Hindari paragraf teks yang besar yang sulit dipindai dan memerlukan scroll vertikal; lebih baik gunakan informasi yang disajikan dalam potongan-potongan kecil.
Usahakan tidak lebih dari 5 langkah dan 3 cuplikan kode per halaman.
Idealnya, paragraf terdiri dari 5 baris atau kurang dan membahas satu konsep.
Jika halaman harus panjang, usahakan agar panjangnya maksimum dua kali lipat panjang panel.
Blok kode dan terminal harus cukup kecil agar dapat dibaca:
- Usahakan 10 baris atau kurang.
- Usahakan 80 karakter atau kurang per baris, untuk mengurangi scroll horizontal.
- Hindari blok kode multi-perintah untuk mencegah pengguna harus melakukan salin-eksekusi massal.
Halaman pengantar: Mulai tutorial Anda dengan pengantar.
- Tetapkan ekspektasi: Jelaskan secara singkat bagaimana pengguna Anda akan mendapatkan keuntungan dari menyelesaikan tutorial ini.
- Perkiraan komitmen waktu: Perkirakan secara kasar berapa lama pengguna dapat menghabiskan waktu 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 dengan kata-kata padat), pertimbangkan untuk membaginya menjadi serangkaian tutorial yang lebih kecil.
- Bersikap terus terang: Nyatakan dengan jelas sumber daya atau akses prasyarat yang mungkin perlu disiapkan pengguna agar dapat mengikuti tutorial tanpa terganggu.
Contoh ## Mari kita mulai!
Buat pengguna Anda dapat menggunakan project Anda dengan cepat dengan menyertakan tutorial interaktif.
Panduan ini akan menunjukkan cara membuat tutorial interaktif Anda sendiri (seperti tutorial ini). Bagian ini juga akan memandu Anda membuat tombol yang dapat digunakan pengguna untuk meluncurkan tutorial yang telah selesai.
**Waktu penyelesaian**: Sekitar 10 menit
**Prasyarat**: Akun Penagihan Cloud
Klik tombol **Lanjutkan** untuk melanjutkan ke langkah berikutnya.
Halaman latar belakang
- Menyiapkan latar: Saat menulis tutorial, sering kali berguna untuk memberikan konteks. Hal ini dapat berarti memberikan ringkasan singkat tentang produk atau dengan cepat menjelaskan fitur penting UI.
Contoh ## Apa itu Cloud Shell?
Sebelum Anda memulai, mari kita bahas secara singkat apa yang dapat dilakukan Cloud Shell.
Cloud Shell adalah Virtual Machine yang dihosting secara pribadi dan telah 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 Anda dengan cepat; memberi mereka kesempatan untuk mempelajari kasus penggunaan dan memahami fungsi project Anda.
Lanjutkan ke langkah berikutnya untuk mulai menyiapkan tutorial Anda.
Contoh Dasar:
- Halo Dunia: Contoh pertama yang Anda berikan harus cukup sederhana agar pengguna dapat mengujinya tanpa banyak penjelasan. Ini harus setara dengan Hello World Anda. Gunakan contoh ini sebagai dasar untuk terus membangun guna mencontohkan 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 memulai penggunaan project Anda melalui pengalaman satu layar yang sederhana.
Coba jalankan perintah sekarang:
```bash
echo "Hello Cloud Shell"
```
**Tips**: Klik tombol salin di samping kotak kode untuk menempelkan perintah di terminal Cloud Shell untuk menjalankannya.
Selanjutnya, Anda akan menulis dan meluncurkan tutorial dasar.
Konten Tutorial
- Format dengan hati-hati: Pemformatan teks (tebal, miring, dll.) 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 penting untuk konteks, sertakan link tambahan ([teks link](URL link)) agar pengguna dapat melakukan riset mereka sendiri.
- Pilih sorotan daripada screenshot: Sorotan, tindakan yang menyoroti lokasi elemen UI di Google Cloud konsol, 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 yang lebih intuitif dan praktik terbaik.
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 ('# Introduction to writing tutorials in 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 antar-langkah, 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 telah meluangkan waktu untuk menyelesaikan tutorial.
- Kesimpulan: Ringkas pelajaran penting yang ingin Anda sampaikan kepada pengguna dari tutorial ini.
- Langkah berikutnya: Bantu pengguna dalam perjalanan mereka dengan memberikan langkah-langkah berikutnya - langkah-langkah ini dapat berupa bacaan yang direkomendasikan, referensi tambahan, atau bahkan, tutorial lain.
- Perhatikan pengguna Anda: Sarankan mereka untuk membersihkan semua resource pengujian yang mereka buat untuk tujuan tutorial guna menghindari biaya penagihan yang tidak diinginkan.
Contoh ## Selamat
<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>
Anda sudah siap!
Sekarang Anda dapat meminta pengguna 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 setelah Anda selesai**: Jika Anda membuat project pengujian, pastikan untuk menghapusnya agar terhindar dari biaya yang tidak perlu. Gunakan `gcloud projects delete <PROJECT-ID>`.