Aturan Menulis Tutorial Perangkat Lunak

xguru · 2025-01-15T10:41:02+09:00

Sebagian besar tutorial perangkat lunak membuat pembaca tidak dapat mereproduksi prosesnya karena melewatkan detail penting atau memuat asumsi tersembunyi yang tidak sesuai dengan harapan pembaca Dengan mengikuti beberapa aturan sederhana, menulis tutorial yang luar biasa ternyata lebih mudah daripada yang dibayangkan Aturan Menulis untuk pemula Buat judul yang menjanjikan hasil yang jelas Jelaskan tujuan di bagian pendahuluan Tunjukkan hasil akhir lebih dulu Tulis snippet kode yang bisa di-copy/paste Gunakan flag panjang pada perintah Pisahkan nilai kustom pengguna dan logika yang dapat digunakan ulang Kurangi upaya pembaca Tulis agar kode selalu tetap berfungsi Ajarkan hanya satu topik Utamakan kejelasan daripada hiasan Minimalkan dependensi Sebutkan nama file dengan jelas Gunakan judul yang konsisten dan deskriptif Buktikan bahwa solusinya berfungsi Tautkan contoh yang lengkap Menulis untuk pemula Kesalahan paling umum dalam tutorial adalah menjelaskan konsep tingkat pemula dengan istilah tingkat ahli. Kebanyakan orang yang mencari tutorial adalah pemula. Mereka mungkin bukan pemula dalam pemrograman, tetapi tetap pemula dalam domain yang ingin dipelajari Tulis untuk pembaca pemula, dan hindari penggunaan istilah tingkat ahli Hindari istilah yang sulit dan tulislah dengan bahasa sederhana yang bisa dipahami pembaca Misalnya, dalam tutorial React, berikan penjelasan seperti "membuat halaman web sederhana dengan React" alih-alih "JSX transpilation" Buat judul yang menjanjikan hasil yang jelas Judul harus menyampaikan secara spesifik apa yang bisa dipelajari pembaca dari tutorial tersebut Hindari judul yang tidak jelas atau ambigu, dan jelaskan hasil yang diharapkan dengan tegas Contoh: "Build a Real-Time Twitter Clone in 15 Minutes with Phoenix LiveView" Jelaskan tujuan di bagian pendahuluan Saat pembaca mengklik tutorial, itu berarti mereka tertarik dengan apa yang Anda sampaikan. Namun, Anda masih harus meyakinkan mereka untuk terus membaca Ada dua hal yang ingin diketahui pembaca Apakah saya perlu tertarik pada teknologi ini? Jika ya, apakah tutorial ini cocok untuk saya? Di bagian pendahuluan, jelaskan secara ringkas pentingnya teknologi tersebut dan kegunaan tutorialnya Berikan informasi yang berguna agar pembaca tertarik, dan hindari penjelasan yang samar Contoh: tutorial Docker harus menjelaskan dengan jelas masalah yang diselesaikan Docker dan hasil yang dapat diharapkan Tunjukkan hasil akhir lebih dulu Secepat mungkin, tampilkan demo kerja atau tangkapan layar dari hal yang akan dibuat pembaca melalui tutorial Menunjukkan hasil akhir di awal tutorial membantu memperjelas tujuan Contoh: sediakan tangkapan layar produk akhir, UI, atau contoh cara kerjanya Tulis snippet kode yang bisa di-copy/paste Tulis agar pembaca bisa dengan mudah menyalin kode, menempelkannya ke editor atau terminal, lalu langsung menjalankannya Hapus elemen yang tidak perlu seperti karakter prompt terminal $ Gunakan flag non-interaktif untuk menyederhanakan perintah, dan gunakan && agar proses berhenti saat gagal Gunakan flag panjang pada perintah Dalam perintah, gunakan flag panjang yang lebih jelas penjelasannya daripada flag pendek agar mudah dipahami pemula gunakan --recursive daripada -r Pisahkan nilai kustom pengguna dan logika yang dapat digunakan ulang Dalam kode, pisahkan dengan jelas nilai yang harus diubah pengguna dan kode yang tidak boleh diubah Gunakan environment variable untuk mendefinisikan nilai kustom pengguna dan meningkatkan keterbacaan kode Kurangi upaya pembaca Hormati waktu pembaca agar mereka menyukai tutorial Anda Ganti pekerjaan yang membosankan dengan snippet perintah Contoh: selesaikan dengan perintah alih-alih mengedit file secara manual Tulis agar kode selalu tetap berfungsi Contoh kode harus selalu dapat dijalankan, dan tetap berfungsi bahkan di langkah-langkah perantara Kode yang salah atau contoh yang tidak berjalan akan membingungkan pembaca Ajarkan hanya satu topik Tulis tutorial dengan berfokus pada satu topik, dan jangan mencampurkan teknologi yang tidak relevan Misalnya, jangan menambahkan teknologi AI yang tidak perlu ke tutorial yang menjelaskan fitur pencarian Utamakan kejelasan daripada hiasan Pembaca tidak peduli apakah aplikasi mainan terlihat indah Minimalkan CSS atau elemen desain yang tidak perlu, dan fokus pada konsep inti Sampaikan konsep dengan jelas menggunakan kode sederhana alih-alih contoh yang rumit Minimalkan dependensi Minimalkan dependensi yang harus dipasang pembaca agar tutorial lebih mudah diakses Sebutkan dependensi yang wajib dengan jelas, dan cantumkan versi tertentu Sebutkan nama file dengan jelas Beri tahu pembaca secara tepat path file dan isi yang harus diubah Misalnya, alih-alih "tambahkan pengaturan ke file config", berikan path file lengkap dan kode yang spesifik tentang baris mana yang harus diedit Gunakan judul yang konsisten dan deskriptif Gunakan heading yang terstruktur agar pembaca mudah memindai tutorial Gunakan judul untuk menyusun tutorial dan tulislah agar mencerminkan struktur yang logis Pertahankan format, sudut pandang, dan kala judul secara konsisten Buktikan bahwa solusinya berfungsi Jika tutorial mengajarkan pemasangan alat atau integrasi beberapa komponen, tunjukkan cara menggunakan hasilnya Tunjukkan secara visual kepada pembaca hasil kerja dari alat yang dipasang atau diintegrasikan Misalnya, tampilkan halaman sukses nginx dan berikan cara memverifikasinya melalui URL Tautkan contoh yang lengkap Tautkan repositori yang memuat seluruh kode tutorial agar alur lengkapnya bisa ditinjau Bagi kode setiap langkah ke branch git terpisah agar pembaca bisa mengikuti tiap tahap

(refactoringenglish.com)

70 poin oleh xguru 2025-01-15 | 11 komentar | Bagikan ke WhatsApp

Sebagian besar tutorial perangkat lunak membuat pembaca tidak dapat mereproduksi prosesnya karena melewatkan detail penting atau memuat asumsi tersembunyi yang tidak sesuai dengan harapan pembaca
Dengan mengikuti beberapa aturan sederhana, menulis tutorial yang luar biasa ternyata lebih mudah daripada yang dibayangkan

Aturan

Menulis untuk pemula
Buat judul yang menjanjikan hasil yang jelas
Jelaskan tujuan di bagian pendahuluan
Tunjukkan hasil akhir lebih dulu
Tulis snippet kode yang bisa di-copy/paste
Gunakan flag panjang pada perintah
Pisahkan nilai kustom pengguna dan logika yang dapat digunakan ulang
Kurangi upaya pembaca
Tulis agar kode selalu tetap berfungsi
Ajarkan hanya satu topik
Utamakan kejelasan daripada hiasan
Minimalkan dependensi
Sebutkan nama file dengan jelas
Gunakan judul yang konsisten dan deskriptif
Buktikan bahwa solusinya berfungsi
Tautkan contoh yang lengkap

Menulis untuk pemula

Kesalahan paling umum dalam tutorial adalah menjelaskan konsep tingkat pemula dengan istilah tingkat ahli. Kebanyakan orang yang mencari tutorial adalah pemula.
- Mereka mungkin bukan pemula dalam pemrograman, tetapi tetap pemula dalam domain yang ingin dipelajari
Tulis untuk pembaca pemula, dan hindari penggunaan istilah tingkat ahli
Hindari istilah yang sulit dan tulislah dengan bahasa sederhana yang bisa dipahami pembaca
Misalnya, dalam tutorial React, berikan penjelasan seperti "membuat halaman web sederhana dengan React" alih-alih "JSX transpilation"

Buat judul yang menjanjikan hasil yang jelas

Judul harus menyampaikan secara spesifik apa yang bisa dipelajari pembaca dari tutorial tersebut
Hindari judul yang tidak jelas atau ambigu, dan jelaskan hasil yang diharapkan dengan tegas
- Contoh: "Build a Real-Time Twitter Clone in 15 Minutes with Phoenix LiveView"

Jelaskan tujuan di bagian pendahuluan

Saat pembaca mengklik tutorial, itu berarti mereka tertarik dengan apa yang Anda sampaikan. Namun, Anda masih harus meyakinkan mereka untuk terus membaca
Ada dua hal yang ingin diketahui pembaca
- Apakah saya perlu tertarik pada teknologi ini?
- Jika ya, apakah tutorial ini cocok untuk saya?
Di bagian pendahuluan, jelaskan secara ringkas pentingnya teknologi tersebut dan kegunaan tutorialnya
Berikan informasi yang berguna agar pembaca tertarik, dan hindari penjelasan yang samar
- Contoh: tutorial Docker harus menjelaskan dengan jelas masalah yang diselesaikan Docker dan hasil yang dapat diharapkan

Tunjukkan hasil akhir lebih dulu

Secepat mungkin, tampilkan demo kerja atau tangkapan layar dari hal yang akan dibuat pembaca melalui tutorial
- Menunjukkan hasil akhir di awal tutorial membantu memperjelas tujuan
Contoh: sediakan tangkapan layar produk akhir, UI, atau contoh cara kerjanya

Tulis snippet kode yang bisa di-copy/paste

Tulis agar pembaca bisa dengan mudah menyalin kode, menempelkannya ke editor atau terminal, lalu langsung menjalankannya
Hapus elemen yang tidak perlu seperti karakter prompt terminal $
Gunakan flag non-interaktif untuk menyederhanakan perintah, dan gunakan && agar proses berhenti saat gagal

Gunakan flag panjang pada perintah

Dalam perintah, gunakan flag panjang yang lebih jelas penjelasannya daripada flag pendek agar mudah dipahami pemula
- gunakan --recursive daripada -r

Pisahkan nilai kustom pengguna dan logika yang dapat digunakan ulang

Dalam kode, pisahkan dengan jelas nilai yang harus diubah pengguna dan kode yang tidak boleh diubah
Gunakan environment variable untuk mendefinisikan nilai kustom pengguna dan meningkatkan keterbacaan kode

Kurangi upaya pembaca

Hormati waktu pembaca agar mereka menyukai tutorial Anda
Ganti pekerjaan yang membosankan dengan snippet perintah
- Contoh: selesaikan dengan perintah alih-alih mengedit file secara manual

Tulis agar kode selalu tetap berfungsi

Contoh kode harus selalu dapat dijalankan, dan tetap berfungsi bahkan di langkah-langkah perantara
Kode yang salah atau contoh yang tidak berjalan akan membingungkan pembaca

Ajarkan hanya satu topik

Tulis tutorial dengan berfokus pada satu topik, dan jangan mencampurkan teknologi yang tidak relevan
Misalnya, jangan menambahkan teknologi AI yang tidak perlu ke tutorial yang menjelaskan fitur pencarian

Utamakan kejelasan daripada hiasan

Pembaca tidak peduli apakah aplikasi mainan terlihat indah
Minimalkan CSS atau elemen desain yang tidak perlu, dan fokus pada konsep inti
Sampaikan konsep dengan jelas menggunakan kode sederhana alih-alih contoh yang rumit

Minimalkan dependensi

Minimalkan dependensi yang harus dipasang pembaca agar tutorial lebih mudah diakses
Sebutkan dependensi yang wajib dengan jelas, dan cantumkan versi tertentu

Sebutkan nama file dengan jelas

Beri tahu pembaca secara tepat path file dan isi yang harus diubah
Misalnya, alih-alih "tambahkan pengaturan ke file config", berikan path file lengkap dan kode yang spesifik tentang baris mana yang harus diedit

Gunakan judul yang konsisten dan deskriptif

Gunakan heading yang terstruktur agar pembaca mudah memindai tutorial
Gunakan judul untuk menyusun tutorial dan tulislah agar mencerminkan struktur yang logis
Pertahankan format, sudut pandang, dan kala judul secara konsisten

Buktikan bahwa solusinya berfungsi

Jika tutorial mengajarkan pemasangan alat atau integrasi beberapa komponen, tunjukkan cara menggunakan hasilnya
- Tunjukkan secara visual kepada pembaca hasil kerja dari alat yang dipasang atau diintegrasikan
Misalnya, tampilkan halaman sukses nginx dan berikan cara memverifikasinya melalui URL

Tautkan contoh yang lengkap

Tautkan repositori yang memuat seluruh kode tutorial agar alur lengkapnya bisa ditinjau
Bagi kode setiap langkah ke branch git terpisah agar pembaca bisa mengikuti tiap tahap

11 komentar

godogi7 2025-02-12

Sebagai referensi

wedding 2025-01-16

Yang seperti ini, bookmark dulu!

ilikeall 2025-01-16

Tulisan yang bagus.

halfenif 2025-01-16

Belakangan ini saya mencoba mengikuti tutorial dagster. Saya merasa tutorialnya dibuat dengan baik.

https://courses.dagster.io/

aer0700 2025-01-16

Saya melihat-lihat tutorial Dagster dan ternyata sangat bagus.
Tutorial Django isinya memang berbobot, tetapi terlalu panjang jadi saya pribadi agak kurang suka. Saya harap bisa dipecah menjadi beberapa bagian.

savvykang 2025-01-16

Ada juga Django sebagai contoh tutorial yang dibuat dengan baik: https://docs.djangoproject.com/en/5.1/intro/tutorial01/

jhj0517 2025-01-16

Gunakan bahasa yang sederhana & tampilkan hasil akhir terlebih dahulu.

aer0700 2025-01-15

Sering ada dokumen tutorial yang alih-alih menunjukkan cara penggunaan dasar framework yang membosankan,
justru ingin memperlihatkan betapa kerennya framework ini.
Saya sangat tidak suka kalau masuk ke Get started lalu yang diberi label tutorial penggunaan dasar ternyata dokumennya sampai 10 halaman.

beenzinozino 2025-01-16

Semuanya luar biasa sekali...

savvykang 2025-01-15

https://tanstack.com/table/latest/docs/introduction

nono9633 2025-01-15

https://github.com/tmux/tmux/wiki/Getting-Started