Tutorial adalah janji: ikuti langkahnya dan Anda akan berakhir di tempat yang lebih baik daripada saat mulai. Mengingkari janji itu membuat pembaca kehilangan satu sore. Topik ini mengumpulkan cara kami menulis dan merawat tutorial serta panduan how-to — strukturnya, kebiasaannya, dan proses review yang membuatnya tetap berguna berbulan-bulan kemudian.
Apa yang membuat sebuah panduan layak terbit
Sebagian besar dokumentasi yang buruk bukan ditulis dengan buruk, melainkan salah lingkup. Sebelum menulis satu langkah pun, kami menjawab empat pertanyaan:
- Untuk siapa ini? “Semua orang” berarti tidak ada siapa pun. Panduan untuk orang yang belum pernah membuka terminal adalah artikel yang berbeda dari panduan untuk developer yang sudah men-deploy setiap minggu.
- Apa yang mereka punya di akhir? Hasil nyata yang bisa mereka periksa sendiri, bukan sekadar rasa sudah membaca sesuatu.
- Apa yang harus sudah mereka miliki? Akun, akses, perkakas, dan versi — disebutkan di awal, karena prasyarat yang hilang adalah penyebab kegagalan tutorial yang paling umum.
- Apa yang bisa salah? Tiga atau empat cara pembaca benar-benar tersangkut, dan apa yang harus dilakukan untuk masing-masingnya.
Kalau jawaban keempat hal itu masih kabur, panduannya belum siap ditulis — ia baru siap ditentukan lingkupnya.
Struktur yang kami pakai
Setiap tutorial kami mengikuti kerangka yang sama, karena pembaca tidak seharusnya belajar format baru di setiap halaman:
Prasyarat
Daftar singkat sebelum langkah pertama: versi, hak akses, waktu yang dibutuhkan, dan apa yang diasumsikan sudah dipahami pembaca. Apa pun yang tidak ada di daftar ini tidak boleh dibutuhkan di langkah berikutnya.
Langkah yang masing-masing mengerjakan satu hal
Satu aksi per langkah, satu hasil per langkah. “Buat berkasnya, tempel isinya, lalu restart layanannya” adalah tiga langkah, karena tiga hal bisa salah. Langkah bernomor lebih mudah dilanjutkan daripada paragraf — kebanyakan pembaca kembali ke tutorial dari tengah.
Verifikasi
Setelah semua langkah, bagaimana Anda tahu berhasil? Sebuah perintah untuk dijalankan, halaman untuk dibuka, nilai untuk dibandingkan. Tutorial tanpa verifikasi membuat pembaca harus menebak-nebak.
Penanganan masalah
Galat yang benar-benar muncul saat panduan diuji, lengkap dengan penyebab dan solusinya. Bukan “cek log Anda” yang serba umum, melainkan dua atau tiga pesan spesifik yang akan ditemui pembaca.
Ke mana selanjutnya
Satu atau dua langkah lanjutan yang jujur. Di sini kami juga menautkan panduan terkait di topik yang sama, alih-alih meninggalkan pembaca di jalan buntu.
Menulis untuk yang menyimak sekilas dan yang menyalin
Orang jarang membaca panduan dari awal sampai akhir. Mereka menyimak judul, menyalin blok yang terlihat relevan, lalu lanjut. Karena itu:
- Judul menyebut aksinya, bukan konsepnya: “Setel environment variable”, bukan “Konfigurasi”.
- Blok kode lengkap dan siap tempel. Tanpa
…di tengah, tanpa mencampur beberapa sesi terminal dalam satu blok, tanpa placeholder yang diam-diam membuat perintah gagal. - Perintah dan path berkas ditampilkan dalam urutan yang sama dengan langkah yang menjelaskannya.
- Tanpa keadaan tersembunyi. Kalau sebuah langkah bergantung pada terminal yang berada di direktori tertentu, atau layanan yang sudah berjalan, kami menyebutnya di tempat yang tepat.
- Tangkapan layar hanya kalau layarnya memang inti pembahasan — dialog dengan lima opsi, pengaturan di dalam menu. Untuk kode, teks selalu lebih baik daripada gambar.
Jaga perintah, versi, dan tangkapan layar tetap jujur
Perangkat lunak terus berubah, artinya panduan bisa rusak. Tiga kebiasaan membatasi kerusakannya:
- Sematkan versi bila versinya penting dan sebutkan tanggal panduan diperiksa, supaya pembaca bisa menilai apakah isinya masih berlaku.
- Uji di mesin bersih, bukan di laptop kami. Langkah yang hanya berhasil karena ada sesuatu yang dipasang enam bulan lalu bukanlah langkah.
- Perbarui, arsipkan, atau alihkan — jangan biarkan langkah basi berdiri. Kalau panduan masih berguna tapi kedaluwarsa, kami perbarui di tempat dan memberi tanggal “diperbarui”. Kalau sudah tidak relevan, kami arsipkan atau mengalihkan URL-nya supaya tautan yang sudah tersebar tetap bekerja.
Merawat pustaka panduan agar tidak membusuk
Kebiasaan kecil hanya berguna kalau dijalankan bersama. Kami menyimpan daftar sederhana untuk setiap panduan di sebuah proyek: siapa pemiliknya, kapan terakhir diverifikasi, dan apa saja ketergantungannya. Panduan untuk audiens yang sama diletakkan di topik yang sama, sehingga pembaca yang menyelesaikan satu masalah bisa menemukan jawaban tetangganya tanpa kembali ke mesin pencari.
Daftar itu juga yang menentukan apa yang kami tulis berikutnya: pertanyaan yang paling sering kami jawab untuk klien dan rekan kerja, sesuai urutan frekuensinya.
Apa yang kami terbitkan di topik Tutorial & How-To
Artikel di topik ini berupa panduan praktis dari awal sampai akhir: menyiapkan proyek dari nol, menghubungkan domain, mengunggah media ke object storage, menambah redirect, mengukur kecepatan halaman, dan memulihkan keadaan ketika deploy bermasalah. Semuanya diuji lebih dulu sebelum terbit — dan diperiksa ulang saat perkakas di baliknya berubah.
Punya masalah yang berulang kali Anda selesaikan secara manual? Ceritakan kepada kami dan itu bisa menjadi panduan berikutnya di sini.