Mendokumentasikan plugin dan tema WordPress

Diterbitkan: 2017-03-17

Dokumentasi adalah sesuatu yang biasanya hanya dihargai ketika ada masalah dan Anda membutuhkan jawaban dengan cepat. Pada artikel ini, kita akan membahas alasan mengapa menulis dokumentasi untuk aset WordPress Anda penting untuk praktik Anda sebagai pengembang WordPress dan kualitas tema dan plugin yang Anda kirimkan.

Mengapa dokumentasi penting?

Menjaga kumpulan dokumentasi terbaru tentang proyek, aset, atau produk Anda penting karena berbagai alasan.

Pertama, itu adalah pengalaman umum melihat sesuatu yang Anda buat 2 bulan yang lalu dan belum pernah disentuh sejak itu, dan tidak tahu apa artinya. Ketika Anda mengembangkannya, Anda memiliki semuanya di dalam kepala Anda tetapi pemahaman itu tidak akan ada di masa depan. Jadi baik menggunakan komentar kode sebaris atau menulis catatan teks biasa dalam penurunan harga, sangat membantu menyelamatkan diri Anda di masa depan dari kebingungan.

Kedua, menjaga aset Anda didokumentasikan sangat membantu bagi pengembang WordPress lainnya. Dan ini masuk akal bahkan jika Anda adalah seorang freelancer tunggal (Anda pasti akan berkolaborasi dengan orang lain di beberapa titik). Mereka akan perlu menggunakan aset tersebut atau akan diminta untuk memeliharanya dan/atau memperbaruinya. Sangat frustasi harus menggunakan kode tidak berdokumen yang ditulis oleh orang lain, yang tidak ada untuk memberikan dukungan atau menjelaskan beberapa bagian yang sulit.

Akhirnya, dokumentasi menambahkan bahwa tampilan "halus" ke produk Anda dan pelanggan Anda akan lebih mencintai Anda.

5 prinsip untuk dokumentasi yang efektif

Penulisan teknis adalah disiplin tersendiri dan digunakan untuk mengkomunikasikan informasi teknis dengan cara yang jelas dan tidak ambigu. (Tidak terbatas pada komputer saja, pengacara dan dokter, misalnya, juga menggunakan bahasa teknis mereka sendiri). Oleh karena itu, sebuah dokumen yang dianggap sebagai penulisan teknis biasanya mengikuti gaya tertentu dan mematuhi seperangkat aturan.

Mari kita bahas 5 hal terpenting agar Anda bisa menulis dokumentasi yang efektif untuk produk Anda!

Lebih suka menggunakan lebih sedikit kata daripada yang biasanya Anda gunakan dalam tulisan Anda: Setiap kata harus memiliki tujuan. Bersikaplah langsung dan sederhana. Dokumentasi biasanya dicari ketika seseorang dalam kesulitan dan ingin cepat menemukan solusi. Misalnya, kalimat seperti "Kegagalan untuk menghancurkan Objek Q akan menyebabkan kebocoran memori" lebih disukai daripada "Kegagalan untuk menghancurkan Objek Q akan menyebabkan kebocoran memori".
Lebih suka menggunakan suara aktif daripada pasif: " Klik tombol di kanan atas" daripada "Tombol di kanan atas perlu diklik ". Menggunakan suara aktif menghilangkan ambiguitas tentang siapa yang melakukan apa. Suara pasif hanya digunakan ketika Anda perlu fokus pada objek, bukan pada subjek (misalnya, Platform Pressidium dibuat dengan mempertimbangkan keamanan ) .
Gunakan bahasa deskriptif saat Anda perlu menjelaskan konsep, dan imperatif saat Anda perlu menjelaskan prosedur langkah demi langkah (seperti tutorial).
Gunakan daftar poin-poin ketika Anda perlu membuat daftar hal-hal yang tidak memiliki urutan, dan daftar bernomor ketika urutan poin penting.
Pastikan Anda telah menguji sendiri instruksinya, sebelum menyajikannya!

Mendokumentasikan plugin WordPress

Plugin WordPress seperti perangkat lunak lainnya. Mereka menyediakan fungsionalitas tertentu, mereka memerlukan instalasi, dan terkadang pemecahan masalah juga. Tidak peduli seberapa sederhananya, selalu merupakan ide yang baik untuk menyediakan dokumentasi dalam jumlah yang memadai, karena tidak semua pengguna memiliki keahlian teknis yang sama.

Menerbitkan plugin WordPress Anda di wordpress.org akan memberi Anda tempat untuk meletakkan instruksi instalasi, tangkapan layar, FAQ, bahkan Changelog! Mengisinya dengan informasi yang berguna dan berkualitas adalah kunci untuk membuat plugin Anda menjadi lebih populer:

Tulis deskripsi yang menarik dan bermanfaat yang pada akhirnya akan membuat pengguna mengunduh plugin Anda dan mengunjungi situs web Anda.
Tambahkan tangkapan layar beranotasi yang menjelaskan setiap item konfigurasi plugin Anda selain yang menunjukkan tampilan plugin Anda di browser.
Letakkan pertanyaan di FAQ yang tidak basi. Cara yang baik untuk menemukan kasus tepi yang aneh adalah dengan meminta teman yang tidak paham komputer untuk menggunakan plugin Anda.
Miliki Changelog yang diperbarui dan ditulis dengan baik. Kalimat singkat dan samar adalah larangan besar dan menunjukkan bahwa Anda tidak terlalu peduli dengan pengguna Anda.
Pastikan kode plugin Anda dikomentari dengan baik dan mengikuti praktik perangkat lunak terbaik dan standar pengkodean resmi.

Jika Anda buntu dan butuh inspirasi, lakukan riset kecil-kecilan dan lihat bagaimana teks ditulis di plugin populer yang memiliki ratusan ribu instalasi, dibandingkan dengan plugin yang jarang digunakan.

Mendokumentasikan tema WordPress

Mendokumentasikan tema WordPress adalah masalah yang sama sekali berbeda. Masalah paling umum dengan tema WordPress adalah tidak mengetahui bagian mana yang sesuai dengan elemen visual apa. Tidak semua orang fasih dalam CSS:

Buat hierarki semua bagian CSS Anda, dengan deskripsi yang sesuai.
Untuk setiap bagian, tambahkan tangkapan layar beranotasi yang merinci setiap fungsi, bersama dengan contoh kecil. Jangan lupa untuk menggunakan suara aktif dan bahasa imperatif, saat menunjukkan cara melakukan sesuatu yang mengharuskan pengguna untuk mengikuti instruksi.
Gunakan alat seperti css_doc untuk membantu Anda. Ini menghasilkan gaya dokumentasi JavaDoc dan dapat dipublikasikan.
Terkadang komentar kode tidak cukup dan Anda perlu membuat dokumen Panduan Gaya untuk tema CSS Anda. Dokumen panduan gaya menjelaskan bagaimana elemen perlu terlihat dan dalam kasus apa elemen tersebut perlu digunakan. Mereka menegakkan konsistensi dan membuat kolaborasi lebih mudah juga. Lihat contoh ini oleh Google.
Gunakan kerangka kerja CSS seperti Blueprint CSS. Ini akan membantu Anda dalam pengembangan dengan memberi Anda seperangkat alat seperti kisi yang dapat disesuaikan, tipografi default yang berfungsi, pengaturan ulang CSS browser, dan banyak lagi.
Sekali lagi, jangan lupa untuk berkonsultasi dengan standar pengkodean CSS WordPress resmi.