Bantuan:Dokumentasi templat dan modul
Templat dan modul merupakan dua fitur MediaWiki yang amat berguna, tetapi bisa membingungkan bagi pengguna baru maupun pengguna lama, terutama apabila ditulis dengan rumit. Oleh karena itu, setiap templat dan modul sebaiknya disertai dengan dokumentasi untuk meningkatkan kemanfaatannya.
Dokumentasi harus menjelaskan apa yang dilakukan oleh templat atau modul dan cara menggunakannya. Khusus untuk templat, dokumentasi sebisa mungkin ditulis dengan sederhana dan pakem yang sama, sehingga pengguna yang tidak terlalu paham tentang seluk-beluk sintaksis templat dapat menggunakannya dengan benar. Hal ini berlaku terutama bagi templat yang sangat banyak digunakan.
Konten
[sunting]Dokumentasi harus mencakup:
- Kategori bagi templat atau modul yang didokumentasikan. Pastikan bahwa semua pranala kategori diapit dengan
<includeonly> … <includeonly>. Perhatikan bahwa modul secara khusus hanya dapat dikategorikan melalui halaman dokumentasi. - Kegunaan dari templat atau modul, apa saja yang dilakukannya, serta kapan harus menerapkannya. Jika ada templat atau modul lain dengan nama atau tujuan serupa, ada baiknya untuk menjabarkan perbedaannya secara jelas, guna mengurangi kemungkinan penggunaan yang salah.
- Parameter dari templat atau modul, baik itu parameter polos (sesuai urutan input) maupun bernama, wajib diisi maupun opsional, beserta kegunaannya. Jika suatu parameter hanya dapat diisi dengan pilihan terbatas (misalnya, “ya”, “tidak” atau angka tertentu), jabarkan semua pilihan yang tersedia dan kegunaannya.
- Contoh pemakaian templat. Tunjukkan teks wiki yang dapat langsung digunakan beserta tampilan visualnya. Teks wiki dapat dijabarkan di dalam apitan
<code> … </code>agar terbaca jelas dan mudah disalin,seperti ini. Jika templat dapat digunakan dalam beberapa cara, misalnya dengan atau tanpa parameter opsional, berikan berbagai contoh untuk setiap cara. - Templat atau modul terkait, utamanya jika templat yang didokumentasikan bergantung pada modul tertentu atau merupakan bagian dari kumpulan templat yang menerapkan satu fungsi umum. Pastikan bahwa setiap templat dalam satu kumpulan ditautkan dari masing-masing templat lainnya, agar memudahkan navigasi.
Dokumentasi ditempatkan pada subhalaman /dokumentasi dari templat atau modul itu sendiri. Halaman modul akan secara otomatis memuat konten dari subhalaman dokumentasi, tetapi halaman templat memerlukan pencantuman templat {{dokumentasi}} untuk memunculkannya. Peletakan dokumentasi pada halaman sendiri membuat dokumentasi lebih mudah untuk disunting, bahkan meskipun templat yang didokumentasikan dilindungi dari penyuntingan. Pengembang MediaWiki secara khusus juga merekomendasikan pemisahan dokumentasi, karena meletakkannya pada halaman templat itu sendiri menambah teks yang dapat memberatkan pemrosesan templat pada ruang nama utama.
Subhalaman dokumentasi
[sunting]Supaya konsisten, subhalaman dokumentasi harus diberi nama dan diformat menggunakan pola umum yang dijabarkan berikut ini.
Untuk halaman dengan judul Templat:X atau Modul:X, subhalaman dokumentasinya mesti dibuat di Templat:X/dokumentasi atau Modul:X/dokumentasi. Kemudian, salin tempel teks wiki berikut sebagai kerangka awal untuk dokumentasi Anda:
{{subhalaman dokumentasi}}
===Kegunaan===
<includeonly><!-- TAMBAHKAN KATEGORI DI SINI -->
</includeonly>
Templat {{subhalaman dokumentasi}} akan menampilkan pesan yang menunjukkan bahwa ini adalah subhalaman dokumentasi, beserta tautan ke halaman utama templat atau modul yang didokumentasikan.
Masukkan dokumentasi setelah baris teratas, dan masukkan kategori di bagian bawah sebagaimana yang sudah ditandai oleh baris komentar. Kemudian simpan subhalaman tersebut.
Seperti yang sudah diterangkan, khusus templat, subhalaman dokumentasi perlu ditampilkan secara manual dengan menggunakan templat dokumentasi. Pada halaman Templat:X yang sudah dibuatkan dokumentasinya, tambahkan kode berikut di baris akhir:
<nowiki><noinclude>{{dokumentasi}}</noinclude></nowiki>
Baris kode ini akan mentransklusikan subhalaman dokumentasi ke halaman utama templat.
Lihat pula
[sunting]{{dokumentasi}}– Mentransklusikan subhalaman dokumentasi pada halaman templat, dan menyediakan pranala untuk mengunjungi, menyunting, dan melihat riwayat dokumentasi{{subhalaman dokumentasi}}– Menjelaskan bahwa konten di bawahnya adalah dokumentasi, dan memerikan pranala ke halaman yang didokumentasikan