Prinsip Penulisan

Hasil riset online 11 Juni 2026. Dipakai sebagai "aturan rumah" setiap kali menulis/merevisi panduan, naskah video, atau teks bantuan di aplikasi pesantren.online.

1. Kenali Pembacanya Dulu#

Riset Nielsen Norman Group tentang pengguna literasi rendah menemukan perilaku yang berbeda dari pengguna mahir:

• Mereka membaca kata per kata (tidak memindai/skimming). Teks panjang = beban berat.
• Pandangan menyempit: elemen di pinggir layar sering tidak terlihat. Maka panduan harus menyebut LOKASI tombol ("di pojok kanan atas").
• Mereka takut salah. Satu pesan error bisa membuat berhenti total. Maka setiap prosedur wajib punya bagian "kalau ada masalah" yang menenangkan.
• Kabar baiknya: teks yang ditulis untuk pembaca lemah juga lebih disukai pembaca mahir. Tidak ada ruginya menyederhanakan.

Pembaca kita: staf pesantren yang terbiasa kerja kertas/Excel, sebagian baru pertama pakai aplikasi web, mengakses dari HP Android atau komputer warnet/kantor.

2. Sepuluh Aturan Bahasa#

1. Tingkat baca anak SMP. Kalau anak kelas 1 SMP tidak paham kalimatnya, tulis ulang. (Anjuran NN/g: kelas 6–8.)
2. Kalimat pendek. Maksimal ±15 kata. Satu kalimat satu ide.
3. Kalimat aktif & langsung. "Klik tombol Simpan" — bukan "Tombol Simpan dapat diklik untuk menyimpan".
4. Tanpa jargon. Dilarang: submit, input, field, browse, upload, export tanpa penjelasan. Pakai padanan: kirim, isi, kolom isian, buka, unggah, unduh ke Excel.
5. Konsisten satu istilah. Sudah pilih "masuk" untuk login? Pakai itu terus. Jangan sesekali "sign in".
6. Sapaan hormat & hangat. "Bapak/Ibu" — bukan "user" atau "Anda" yang dingin.
7. Angka & contoh nyata. "Isi nominal, contoh: 150000 (seratus lima puluh ribu, tanpa titik)" lebih jelas dari "isi nominal yang sesuai".
8. Jelaskan istilah teknis sekali di Kamus Istilah, lalu pakai dengan percaya diri.
9. Hindari singkatan kecuali sudah umum di pesantren (SPP, TU, NIS — boleh; CRUD, CSV — jelaskan).
10. Analogi dunia kertas. "Filter itu seperti memilah tumpukan map: hanya map kelas 1A yang diambil."

3. Struktur Resep (template wajib tiap tugas)#

Setiap tugas ditulis seperti resep masakan, dengan urutan tetap:

## Judul = kalimat tugas ("Menambah Santri Baru")

**Kapan dipakai:** 1 kalimat situasi nyata.
**Siapkan dulu:** daftar bahan (data/berkas yang harus ada di tangan).

**Langkahnya:**
1. Satu aksi saja per nomor.
2. Sebut lokasi + tampilan tombol: "klik tombol biru **Simpan** di kanan bawah".
3. Sertakan apa yang AKAN TERLIHAT setelah aksi ("layar berganti ke daftar santri").

<figure class="shot"><div class="shot-frame">📷</div><figcaption><b>Cuplikan layar:</b> layar X dengan panah ke tombol Y <span class="soon">(gambar menyusul)</span></figcaption></figure>
✅ **Tanda berhasil:** apa yang terlihat kalau sukses.
⚠️ **Kalau ada masalah:** 2–3 kesalahan umum + cara keluar + kalimat penenang
   ("Data tidak akan rusak. Tutup saja, lalu ulangi dari langkah 1.").

Mengapa begitu (ringkasan riset):

• Langkah bernomor urut sesuai urutan kerja — standar semua pedoman user manual.
• "Tanda berhasil" = expected result; pedoman menyarankan selalu tampilkan hasil yang diharapkan tiap langkah/tugas.
• Mulai dari "Kapan dipakai" karena pengguna mencari berdasarkan masalah ("wali tanya tunggakan"), bukan nama fitur.

4. Aturan Visual#

• Otak memproses gambar jauh lebih cepat daripada teks. Setiap langkah yang melibatkan layar baru/tombol penting wajib ada screenshot.
• Screenshot diberi panah/lingkaran merah ke satu hal saja. Satu gambar satu pesan.
• Gambar diletakkan tepat setelah langkah yang dijelaskan, bukan dikumpulkan di akhir.
• Untuk dibagikan via WA: ekspor PDF dengan ukuran huruf besar (min. 12pt), karena banyak yang membaca di layar HP.
• Video pendek (1–3 menit) per tugas sangat efektif untuk segmen gaptek Indonesia — praktik umum di sekolah: video tutorial dibagikan lewat grup WhatsApp. Naskahnya di 🎬 Naskah Video Tutorial.

5. Kerangka Dokumentasi (adaptasi Diátaxis)#

Kerangka Diátaxis membagi dokumentasi jadi 4 jenis — mencampurnya adalah penyebab utama dokumentasi membingungkan:

Untuk segmen gaptek, porsi terbesar = tutorial + resep. Penjelasan teori dibuat sesingkat mungkin dan tidak menghalangi langkah.

6. Uji Coba (wajib sebelum dianggap selesai)#

Pedoman penulisan manual sepakat: manual harus diuji ke orang yang belum pernah pakai aplikasinya.

Cara murah untuk kita:

1. Pilih 1 staf paling gaptek.
2. Beri dia panduan + 1 tugas nyata ("tambahkan santri bernama X").
3. Dilarang membantu. Hanya amati dan catat di mana dia berhenti/bingung.
4. Setiap titik macet = bagian panduan yang harus diperbaiki (bukan orangnya yang bodoh).
5. Ulangi sampai tugas selesai tanpa bantuan.

7. Sumber Riset#

• Nielsen Norman Group — Plain Language for Everyone, Even Experts dan UX Writing FAQs (tingkat baca kelas 6–8, bahasa percakapan).
• Readability Guidelines — Low literacy users dan Plain English (perilaku baca pengguna literasi rendah).
• TechSmith — The Ultimate Guide to Writing User Manuals (visual, quick start, daftar isi).
• UserFocus — Tips for writing user manuals (uji coba ke pengguna baru, hasil yang diharapkan tiap langkah).
• Instructional Solutions — How to Write a User Manual (langkah berurutan, glosarium, asumsikan pembaca tidak tahu apa-apa).
• Helpjuice — 8 Tips For Writing Better User Documentation (bahasa sederhana, struktur step-by-step).
• Diátaxis — diataxis.fr (4 jenis dokumentasi: tutorial, how-to, referensi, penjelasan).
• Konteks Indonesia: Quipper — Solusi Gaptek dan praktik Guru Berbagi Kemdikbud (video tutorial via grup WA paling efektif); contoh format manual operator sekolah: SIPENSEKDIK Banjarmasin (PDF).