Dokumentasi Produk untuk Profesional WordPress

Diterbitkan: 2017-07-28

Dokumentasi produk biasanya dianggap tidak penting, sehingga Anda dapat mengambil jalan pintas. Itu tidak dilihat sebagai sesuatu yang dapat menawarkan nilai kepada klien, atau sebagai sesuatu yang mungkin dapat mempengaruhi area bisnis utama seperti pendapatan dan pemasaran. Memang, sebagai profesional WordPress Anda tidak perlu menulis dokumentasi dengan cara yang sama seperti Atlassian, atau Cisco. Biasanya, ketika orang memikirkan "dokumentasi" mereka membayangkan gambar panduan pengguna yang tebal dan dicetak, diindeks menurut abjad di rak yang sangat besar yang tidak pernah dibaca siapa pun.

Tapi ini telah berubah:

Dengan munculnya Agile dan DevOps, pengiriman perangkat lunak menjadi lebih cepat dan siklus pengembangan juga menjadi lebih dinamis. Dan hasilnya, dokumentasi sekarang mencerminkan keadaan saat ini dalam rilis terbaru, alih-alih menjadi sesuatu yang statis tertulis di atas kertas selamanya. Dokumentasi diintegrasikan ke dalam siklus pengembangan dan diperbarui sesering perangkat lunak.

Mengapa profesional WordPress harus peduli dengan dokumentasi produk?

Dokumentasi yang berguna dan terkini tidak hanya membuat hidup pengguna Anda lebih mudah, tetapi juga menambah tingkat polesan yang menjadi aset pemasaran yang tiada duanya. Sebaliknya, dokumentasi yang buruk berdampak negatif. Anda mungkin pernah mengalami ini sendiri: Anda memiliki masalah yang berusaha keras untuk menemukan solusinya dalam dokumentasi dan ketika tidak, Anda akhirnya frustrasi (dan mungkin marah). Ini hanya akan menjadi lebih buruk jika Anda membayar untuk produk tersebut.

Jika Anda bekerja di agensi WordPress, memberikan dokumentasi di semua area proyek, mulai dari desain awal hingga aset, akan menambah tingkat profesionalisme yang menunjukkan bahwa:

  1. Anda memperhatikan detail.
  2. Anda cukup peduli dengan klien Anda untuk bekerja lebih keras.
  3. Anda transparan dan percaya diri tentang desain dan keputusan proyek teknis Anda.

Mike Puterbaugh, Wakil Presiden Pemasaran di MindTouch menulis artikel Mashable yang menjelaskan 5 alasan dokumentasi produk Anda adalah aset pemasaran. Dia menyimpulkan dengan yang berikut:

Ini bukan pekerjaan yang seksi, tetapi akan memberi Anda rasa hormat dari rekan-rekan Anda, manajemen perusahaan yang lebih efektif, dan tim yang lebih kolaboratif. Karena ini bukan tentang kuartal ini atau tahun ini, melainkan tentang mempengaruhi keunggulan kompetitif dan pertumbuhan jangka panjang.

Sekarang setelah kami memiliki motivasi yang cukup, kami akan:

  1. Jelajahi berbagai jenis dokumentasi produk yang relevan untuk WordPress.
  2. Diskusikan kebutuhan setiap jenis dokumentasi dan tawarkan saran yang dapat ditindaklanjuti.
  3. Tawarkan beberapa panduan awal tentang bagaimana Anda dapat merencanakan dan berkolaborasi dalam dokumentasi produk. Terutama jika Anda bekerja di agensi WordPress.

Jenis dokumentasi produk WordPress

Produk WordPress tidak hanya tentang plugin dan tema. Di bagian ini, kita juga akan membahas bantuan online, REST API, dan hal aneh yang disebut konten mikro.

Plugin WordPress

Dokumentasi plugin WordPress perlu memenuhi dua kelompok: pengguna dan pengembang. Kebutuhan dokumentasi masing-masing berbeda, begitu pula gaya penulisan yang digunakan.

Host situs web Anda dengan Pressidium

GARANSI UANG KEMBALI 60 HARI

LIHAT RENCANA KAMI

Pengguna

Kebutuhan dokumentasi pengguna sebagian besar berkisar pada pemecahan masalah dan konfigurasi. Tambahkan ke ini bahwa Anda perlu menyajikan plugin Anda dengan cara yang menarik sehingga membuat pengguna mencobanya. Setiap plugin memiliki halamannya sendiri di pasar plugin WordPress. Ingatlah poin-poin berikut:

  • Tulis deskripsi yang menarik dan bermanfaat yang mendorong pengunduhan dan penggunaan.
  • Tambahkan screenshot beranotasi dari halaman konfigurasi plugin Dashboard Anda dengan deskripsi.
  • Letakkan pertanyaan di FAQ yang berguna dan tidak basi.
  • Miliki Changelog yang diperbarui dan ditulis dengan baik. Jangan menambahkan catatan samar atau singkat di sana.

Anda harus ingat bahwa ketika pengguna menggunakan dokumentasi, mereka mungkin terburu-buru dan ingin mencari solusi. Tulis dengan jelas, sederhana dan padat. Jangan membuatnya lebih sulit bagi mereka daripada yang sudah ada.

Pengembang

Selain mengikuti praktik perangkat lunak terbaik dan standar pengkodean PHP resmi, Anda harus memusatkan perhatian pada area berikut:

pengait plugin

Ini melakukan pekerjaan memodifikasi perilaku WordPress. Sangat mungkin plugin WordPress Anda menggunakan itu. Karena pengait plugin adalah bagian penting dari kode, Anda harus mendokumentasikan bagaimana Anda menggunakannya dan dalam fungsi WordPress apa mereka terlibat.

tag templat

Tag template adalah cara lain untuk Plugin WordPress untuk meningkatkan fungsionalitas. Dokumentasikan fungsi tag template yang telah Anda tulis. Sertakan contoh bagaimana pengguna atau pengembang lain dapat menggunakan tag di situs WordPress mereka.

pilihan

Opsi adalah cara untuk menyimpan informasi tertentu dalam database WordPress. Ini dilakukan melalui fungsi add_option dan get_options. Dalam hal ini, dokumentasikan parameter yang Anda berikan ke fungsi ini.

basis data

Plugin sering membaca dan menulis banyak hal berbeda dari database. Karena ini adalah operasi dasar, mendokumentasikannya akan sangat membantu pengembang lain memahami cara kerja plugin Anda.

Tema WordPress

Ada dua area berbeda yang dapat Anda buat dokumentasi untuk tema. Yang pertama adalah file sumber. File CSS yang dikomentari lebih mudah dipahami dan dibaca daripada yang tidak. Gunakan alat seperti css_doc untuk membantu Anda. Ini menghasilkan gaya dokumentasi JavaDoc dan dapat diterbitkan:

Area lainnya adalah panduan Gaya. Dokumen-dokumen ini menjelaskan bagaimana elemen perlu terlihat dan dalam kasus apa mereka perlu digunakan. Mereka menegakkan konsistensi dan membuat kolaborasi lebih mudah juga. Anda dapat membaca 20 contoh artikel panduan gaya merek Hubspot yang menakjubkan karena berisi banyak contoh hebat.

Sekali lagi, jangan lupa untuk berkonsultasi dengan standar pengkodean CSS WordPress resmi.

Mendokumentasikan elemen desain dengan detail seperti itu juga membantu orientasi karyawan baru jika Anda adalah agensi WordPress. Panduan gaya dapat digunakan sebagai tutorial atau bahan referensi untuk pekerjaan klien baru dan lama.

Bantuan Daring

Karena bantuan online bertujuan untuk memecahkan masalah pengguna tertentu, memulai dengan daftar tugas dan masalah umum adalah cara yang harus dilakukan. Meskipun daftarnya pada awalnya tidak akan lengkap, luangkan waktu untuk menghasilkan sebanyak mungkin item konkret. Idenya adalah untuk menulis file bantuan online untuk setiap tugas dan masalah ini, dan menautkannya ke informasi terkait. Anda dapat membuat perjalanan pengguna untuk memetakan jalur berbeda yang dapat diambil dan dilakukan pengguna dalam aplikasi Anda. Menyelidiki email dukungan untuk mengetahui pertanyaan umum dan area bermasalah adalah cara yang baik untuk menjaga basis pengetahuan Anda tetap mutakhir dan berguna.

Barry J. Rosenberg, penulis Spring into Technical Writing menawarkan saran berikut untuk menulis file bantuan yang baik:

Simpan setiap file bantuan sesingkat mungkin. Lebih suka daftar bernomor daripada daftar berpoin. Jangan menyimpang, jangan membuat catatan kaki, dan jangan berkeinginan. Jaga agar setiap file bantuan tetap fokus pada satu tugas terpisah.

Konten mikro

Microcontent memiliki dua definisi: yang pertama adalah konten seperti headline dan bagian yang dibaca pengguna, untuk mendapatkan inti dari artikel tertentu. Yang kedua adalah konten kecil yang dapat berdiri sendiri dan digunakan untuk meningkatkan pengalaman pengguna. Salah satu contoh luar biasa yang kami pikirkan adalah bit “beberapa orang sedang mengetik..” Slack. (walaupun Slack penuh dengan konten mikro yang ditulis dengan sangat baik).

Bit itu dipicu ketika lebih dari 3 orang secara bersamaan mengetik di saluran yang sama. Alih-alih hanya mencetak daftar orang yang sedang mengetik, Slack mengambil informasi yang membosankan ini dan menambahkan beberapa kesenangan ke dalamnya. Diskusi mulai menjadi sangat panas, dan itu terlihat. Ini adalah contoh yang sangat baik tentang bagaimana dokumentasi produk (pesan aplikasi adalah bagian dari itu, bukan?) Membuat orang membicarakan Anda (dan membuat meme lucu seperti di atas).

REST API

Mendokumentasikan REST API adalah seni tersendiri. Seperti semua penulisan teknis, Anda harus bertujuan untuk keringkasan, kejelasan, dan kesederhanaan dalam definisi. Karena REST API memiliki format dan seluk-beluknya sendiri, Anda tidak dapat melakukan hal yang lebih buruk daripada mempelajari panduan yang sangat baik untuk mendokumentasikan API oleh Tom Johnson di blognya Saya Lebih Suka Menulis.

Dokumentasi kolaborasi dan perencanaan

Pada akhirnya, dokumentasi harus menjadi bagian dari desain produk. Karena itu, Anda harus mendekatinya sebagai memiliki saluran tambahan dalam siklus perangkat lunak Anda. Ini berarti menggunakan repositori perangkat lunak untuk menyimpan versi dokumentasi terbaru, menggunakan pelacak bug/masalah untuk memantau tugas dan masalah, memasukkan perencanaan proyek dokumentasi ke peta jalan Anda, dan yang tak kalah pentingnya, berkolaborasi dengan orang lain. Garis besar kasar tentang bagaimana memulainya adalah sebagai berikut:

  1. Rekam semua yang ingin diketahui pengguna, serta area yang Anda perlukan untuk menulis teks.
  2. Setelah Anda memiliki semuanya, kelompokkan mereka dalam kategori dan bentuk judul dokumen.
  3. Tulis spesifikasi untuk setiap dokumen yang merinci hal-hal seperti judul, deskripsi, audiens target, media (bentuk dokumen apa), panjangnya, berapa lama waktu yang dibutuhkan, dll.
  4. Tambahkan perkiraan dari spesifikasi dokumentasi ke perencanaan proyek Anda.

Karena dokumentasi produk melintasi semua area, hampir pasti Anda perlu bekerja dengan orang yang berbeda di dalam organisasi. Adalah ide yang baik untuk duduk dan menyepakati semacam proses tentang bagaimana semua ini akan berjalan. Seperti dalam setiap proyek, Anda harus mengidentifikasi pemangku kepentingan yang akan memberikan bantuan teknis, serta mereka yang akan meninjau dan mengedit perubahan.

Host situs web Anda dengan Pressidium

GARANSI UANG KEMBALI 60 HARI

LIHAT RENCANA KAMI

Harus ada tahapan proses yang berbeda. Ini harus memetakan di mana informasi dikumpulkan, kapan dokumen itu ditulis, kapan siap untuk pembacaan bukti sastra, untuk komentar teknis, penerbitan dan semacamnya. Tekankan pada perbedaan antara komentar sastra, teknis, dan terkait konten. Misalnya, itu tidak benar-benar berguna ketika Anda meminta pemimpin tim untuk mengomentari dokumen Anda dan alih-alih informasi terkait teknis, Anda mendapatkan teriakan untuk tata bahasa dan tanda baca.

Penutupan

Dokumentasi produk adalah aset yang terbayar dalam jangka panjang. Ini memberi nilai kepada klien Anda. Bahkan mungkin sangat bagus, seperti dokumentasi API Stripe misalnya, sehingga orang-orang membicarakannya di forum. Ini membangun keterlibatan dan mengiklankan merek dan produk Anda dengan cara yang alami dan kuat. Ketika digabungkan dengan konten mikro yang kreatif, hal itu mencapai apa yang dimaksud Mike Puterbaugh ketika dia mengatakan bahwa dokumentasi produk adalah "senjata rahasia pemasaran".