Apa itu Dokumentasi Perangkat Lunak? Jenis dan Praktik Terbaik untuk Memulai

Jika Anda ingin pengembang dan pengguna akhir mendapatkan nilai sebanyak mungkin dari perangkat lunak Anda, Anda perlu membuat dokumentasi perangkat lunak berkualitas tinggi.

Tapi apa sebenarnya dokumentasi perangkat lunak itu, dan bagaimana Anda bisa membuatnya untuk proyek Anda?

Dalam posting ini, kami akan menggali semua yang perlu Anda ketahui tentang dokumentasi perangkat lunak, termasuk yang berikut ini:

• Apa itu dokumentasi perangkat lunak?
• Berbagai jenis dokumentasi perangkat lunak (dengan contoh)
• Cara menerbitkan dokumentasi perangkat lunak Anda (alat terbaik)
• Beberapa praktik terbaik untuk membuat dokumentasi perangkat lunak yang berkualitas

Mari menggali!

Apa itu Dokumentasi Perangkat Lunak?

Dokumentasi perangkat lunak adalah konten yang membantu pengguna akhir, pengembang, dan/atau karyawan Anda memahami perangkat lunak Anda dan menggunakannya untuk mencapai tujuan mereka secara efektif.

Biasanya, Anda akan menerbitkan dokumentasi perangkat lunak di situs web Anda. Orang kemudian dapat mengaksesnya untuk mempelajari lebih lanjut tentang perangkat lunak Anda dan cara kerjanya.

Dalam definisi luas dokumentasi perangkat lunak, ada berbagai jenis dokumentasi perangkat lunak. Mari kita bahas itu selanjutnya.

Berbagai Jenis Dokumentasi Perangkat Lunak

Secara kasar Anda dapat membagi berbagai jenis dokumentasi perangkat lunak ke dalam beberapa kategori besar.

Pertimbangan pertama adalah untuk tipe orang apa dokumentasi itu ditujukan:

• Dokumentasi pengguna – ini adalah dokumentasi yang Anda buat untuk pengguna akhir produk. Ini membantu mereka memahami cara menggunakan perangkat lunak Anda dari sudut pandang pengguna biasa, yang mungkin atau mungkin tidak memiliki pengetahuan teknis khusus.
• Dokumentasi pengembang – ini lebih merupakan dokumentasi perangkat lunak teknis yang Anda buat untuk pengembang, seperti dokumentasi API.

Pertimbangan kedua adalah apakah dokumentasi ditujukan untuk audiens eksternal atau internal:

• Dokumentasi perangkat lunak eksternal – ini adalah dokumentasi publik yang Anda buat untuk membantu pengguna Anda.
• Dokumentasi perangkat lunak internal – ini adalah dokumentasi pribadi yang Anda buat untuk karyawan Anda guna membantu mereka bekerja lebih efektif dan memahami detail penting.

Misalnya, Anda mungkin memiliki satu set dokumentasi pengembang untuk tim internal Anda untuk membantu mengerjakan perangkat lunak dan satu set dokumentasi pengembang terbuka lainnya untuk pengembang eksternal.

Mari kita uraikan jenis dokumentasi perangkat lunak ini sedikit lebih detail…

Contoh Dokumentasi Perangkat Lunak untuk Dokumentasi Pengembang

• Dokumentasi API – menunjukkan kepada pengembang cara berinteraksi dengan API perangkat lunak Anda.
• Readme – perkenalkan perangkat lunak Anda dan jelaskan fungsinya – biasanya hal pertama yang dibaca orang.
• Catatan rilis – mendokumentasikan rilis baru perangkat lunak Anda, termasuk perubahan penting apa pun.
• Dokumentasi arsitektur – tunjukkan struktur perangkat lunak Anda, kemungkinan termasuk diagram.
• Dokumentasi model data – mendokumentasikan struktur data yang berbeda dalam perangkat lunak Anda, termasuk hubungan antara struktur data yang berbeda.
• Dokumentasi proses – mendokumentasikan proses kunci seperti laporan bug, peta jalan, jaminan kualitas, protokol pengujian, dan sebagainya.

Untuk contoh dokumentasi perangkat lunak nyata dari dokumen yang berfokus pada pengembang, Anda dapat melihat dokumentasi "Pengembang" Gravity Forms yang mencakup berbagai topik seperti:

• Kait PHP (untuk WordPress)
• Objek data
• API PHP
• Basis data
• API REST

Misalnya, seperti inilah dokumentasi REST API:

Contoh Dokumentasi Perangkat Lunak untuk Dokumentasi Pengguna

• Panduan memulai – menunjukkan kepada pengguna cara cepat memulai dan menjalankan perangkat lunak Anda.
• Tutorial untuk kasus penggunaan tertentu – tutorial yang lebih spesifik untuk menyelesaikan tugas tertentu.
• Glosarium istilah/manual referensi – membantu pengguna memahami istilah dan detail utama.
• FAQ – menjawab pertanyaan umum.

Untuk contoh nyata dari apa yang mungkin terlihat seperti dokumentasi perangkat lunak yang berfokus pada pengguna, Anda dapat beralih ke contoh Gravity Forms yang sama dari atas.

Jika Anda melihat artikel Gravity Forms yang lebih berfokus pada pengguna, Anda akan melihat banyak tutorial langkah demi langkah tentang cara menyelesaikan tugas menggunakan antarmuka perangkat lunak, bersama dengan glosarium dan penjelasan fitur utama.

Dibandingkan dengan dokumentasi perangkat lunak pengembang, Anda akan melihat lebih banyak tangkapan layar dan penjelasan bahasa sederhana dan lebih sedikit blok kode.

Cara Menerbitkan Dokumentasi Perangkat Lunak: Tiga Alat Dokumentasi Perangkat Lunak Terbaik

Untuk menerbitkan dokumentasi perangkat lunak Anda di situs web Anda, Anda memerlukan alat dokumentasi perangkat lunak khusus atau beberapa jenis sistem manajemen pengetahuan.

Di bagian ini, kami akan segera membahas beberapa alat dokumentasi perangkat lunak terbaik. Kemudian, di bagian selanjutnya, kita akan membahas beberapa praktik terbaik untuk membuat dokumentasi berkualitas.

Jika Anda ingin melihat lebih dalam di sini, Anda mungkin ingin membaca panduan lengkap kami tentang alat dokumentasi terbaik dan perangkat lunak dokumentasi teknis terbaik.

Basis Pengetahuan Pahlawan

Heroic Knowledge Base adalah plugin dokumentasi dan basis pengetahuan untuk perangkat lunak WordPress sumber terbuka yang populer.

Dengan Basis Pengetahuan Heroic, Anda dapat menghosting sendiri dokumentasi Anda dan mempertahankan kontrol penuh, sambil tetap mengakses semua fitur yang Anda perlukan untuk membuat dokumentasi perangkat lunak yang efektif.

Berikut adalah beberapa fitur inti yang Anda dapatkan dengan Basis Pengetahuan Heroic:

• Editor konten yang fleksibel , termasuk blok bawaan untuk info dan detail gaya penting lainnya.
• Daftar isi otomatis sehingga pengguna dapat dengan cepat melihat konten apa yang tercakup dalam artikel dokumentasi dan melompat ke bagian tertentu.
• Kontrol revisi dan riwayat versi melalui sistem revisi WordPress asli.
• Fitur penemuan konten termasuk pencarian Ajax waktu nyata dengan saran langsung, kategori, dan lainnya.
• Sistem umpan balik pengguna yang memungkinkan orang menilai artikel sebagai membantu atau tidak membantu dan berbagi umpan balik.
• Analitik pencarian sehingga Anda dapat melihat apa yang dicari pengguna, serta istilah pencarian apa pun yang memberikan hasil nol.
• Widget jawaban instan untuk memungkinkan pengguna menelusuri dan mengakses dokumentasi perangkat lunak dari mana saja di situs Anda.

Karena Heroic Knowledge Base dan WordPress keduanya self-hosted dan open-source, Anda juga bebas memodifikasi pengaturan sesuai kebutuhan.

Anda dapat membuatnya menghadap ke publik atau membatasi akses ke dokumentasi Anda dengan berbagai taktik seperti kata sandi, akun pengguna, alamat IP, intranet, dan lainnya.

Basis Pengetahuan Pahlawan mulai dari hanya $149 per tahun.

Baca Dokumen

Read the Docs adalah alat dokumentasi yang difokuskan untuk membantu Anda membuat dokumentasi pengembang.

Jika Anda secara khusus berfokus pada pembuatan dokumentasi developer teknis, ini bisa menjadi opsi lain yang bagus untuk dipertimbangkan.

Anda dapat mengelola konten dan riwayat revisi menggunakan Git, lalu menerapkan dokumen Anda ke antarmuka frontend.

Berikut adalah beberapa fitur penting lainnya di Read the Docs:

• Analitik bawaan untuk melihat apa yang dibaca dan dicari pengguna Anda.
• Mendukung beberapa build bersamaan , yang dapat membantu jika Anda menawarkan beberapa versi perangkat lunak Anda – misalnya satu kumpulan dokumentasi untuk versi 1.0 dan satu lagi untuk versi 2.0.
• Ekspor dokumentasi dalam berbagai format termasuk PDF, HTML, dan epub.
• Saran pencarian langsung untuk membantu pengguna menemukan dokumen.

Baca Dokumen gratis untuk digunakan jika Anda memiliki proyek perangkat lunak sumber terbuka.

Untuk produk perangkat lunak komersial, ada layanan Read the Docs for Business berbayar mulai dari $50 per bulan.

GitBook

GitBook adalah alat dokumentasi perangkat lunak teknis lainnya yang memungkinkan Anda mengelola dokumentasi menggunakan Git, dengan dukungan untuk repositori GitHub dan GitLab.

Atau, jika Anda tidak ingin menggunakan Git, GitBook juga memungkinkan Anda membuat dokumentasi menggunakan editor teks atau mengimpornya dari file markdown atau .doc.

Berikut adalah beberapa fitur penting lainnya yang ditawarkan GitBook:

• Kontrol versi untuk melacak revisi dan riwayat versi.
• Pengeditan tim langsung yang berguna jika Anda memerlukan beberapa penulis untuk berkolaborasi dalam artikel.
• Atur artikel menggunakan "spasi" dan "koleksi" – setiap ruang dapat memiliki banyak koleksi di dalamnya.
• Opsi ekspor PDF sehingga pengguna dapat dengan mudah mengekspor dokumentasi Anda sebagai unduhan PDF.

GitBook gratis untuk proyek nirlaba atau sumber terbuka.

Untuk proyek perangkat lunak komersial, GitBook mulai dari $8 per pengguna per bulan, dengan minimal 5 pengguna. Itu berarti tarif bulanan termurah adalah $40 per bulan.

Praktik Terbaik untuk Membuat Dokumentasi Perangkat Lunak

Untuk menyelesaikannya, mari gali beberapa praktik terbaik dokumentasi perangkat lunak untuk membantu Anda membuat dokumentasi yang efektif.

Pikirkan Tentang Tujuan dan Kebutuhan Pengguna

Saat Anda menulis artikel dokumentasi perangkat lunak, penting untuk memulai dengan menjawab beberapa pertanyaan dasar:

• Untuk siapa pengguna yang Anda tulis?
• Apa yang ingin dicapai oleh pengguna?
• Tingkat pengetahuan teknis apa yang dimiliki pengguna?

Mengetahui jawaban atas pertanyaan-pertanyaan ini akan membantu Anda memahami konten apa yang akan dibahas dan bagaimana menyusun artikel dengan cara yang paling optimal.

Misalnya, Anda menawarkan perangkat lunak penjadwalan media sosial dan Anda sedang menulis artikel yang membantu pengelola media sosial menjadwalkan postingan media sosial pertama mereka.

Saat menulis dokumentasi perangkat lunak Anda, Anda ingin berfokus untuk menunjukkan cara yang paling mudah bagi pengguna akhir biasa untuk mencapai tujuan tersebut.

Jika Anda juga menawarkan API untuk memungkinkan pengembang menyiapkan integrasi mereka sendiri, Anda mungkin ingin membahasnya di artikel lain ( meskipun Anda mungkin menyebutkan dan menautkan ke metode itu ).

Sertakan Dokumentasi Perangkat Lunak dalam Proses Pengembangan

Saat Anda membuat dokumentasi perangkat lunak, mudah jatuh ke dalam perangkap menunggu sampai proyek selesai untuk mendokumentasikannya.

Namun, hal ini dapat dengan cepat menimbulkan utang dokumentasi karena Anda mungkin mengirimkan fitur atau perubahan baru sebelum didokumentasikan.

Untuk menghindari hal ini, jadikan dokumentasi perangkat lunak sebagai bagian sadar dari siklus pengembangan perangkat lunak. Jika fitur atau produk baru belum didokumentasikan, itu belum siap dikirim meskipun kodenya sendiri sudah selesai.

Dengan menjadikan dokumentasi sebagai persyaratan inti dari proses pengembangan perangkat lunak, Anda dapat memastikan bahwa semua yang Anda kirimkan disertai dengan dokumentasi yang tepat.

Gunakan Pemformatan dan Gaya yang Konsisten

Untuk membantu orang bekerja lebih efektif dengan dokumentasi perangkat lunak Anda, penting bagi Anda untuk menggunakan pemformatan dan gaya yang konsisten di semua dokumentasi Anda.

Menggunakan pemformatan yang sama memungkinkan pembaca mempelajari bagaimana dokumentasi perangkat lunak Anda disusun, yang akan memudahkan mereka mengakses informasi yang mereka butuhkan dengan cepat.

Untuk membantu mencapai konsistensi ini, Anda mungkin ingin membuat panduan gaya dokumentasi perangkat lunak khusus.

Alat manajemen dokumentasi perangkat lunak Anda mungkin juga menyertakan fitur untuk membantu Anda mencapai gaya yang konsisten.

Misalnya, plugin Pangkalan Pengetahuan Heroik menyertakan keterangan yang telah ditata sebelumnya untuk menyorot informasi atau peringatan penting. Dengan menggunakan ini, Anda dapat memastikan pemformatan yang konsisten di semua dokumentasi Anda.

Gunakan Pakar Untuk Menulis Dokumentasi Teknis

Untuk dokumentasi perangkat lunak yang menghadap ke pengguna, Anda mungkin tidak memerlukan pakar materi pelajaran untuk menulis konten.

Namun, untuk dokumentasi perangkat lunak yang lebih teknis, seperti dokumentasi API yang berfokus pada pengembang, Anda mungkin ingin menugaskan seseorang dengan pengetahuan teknis yang relevan untuk menulis dokumen tersebut.

Ini bisa menjadi penulis teknis khusus dengan keahlian domain, jika organisasi Anda memiliki sumber daya untuk disewa untuk posisi itu. Atau, bisa jadi salah satu pengembang Anda.

Yang penting penulis memahami aspek teknis perangkat lunak Anda pada tingkat yang cukup dalam untuk menjelaskannya kepada pengguna teknis lainnya.

Permudah Orang Menemukan Konten (Penelusuran/Filter)

Seiring bertambahnya perpustakaan dokumentasi Anda, akan semakin sulit bagi pengguna untuk menemukan artikel dokumentasi yang sesuai dengan kebutuhan mereka.

Untuk mencoba menghindari masalah ini, Anda sebaiknya berfokus pada peningkatan kemampuan dokumentasi perangkat lunak untuk dapat ditemukan.

Salah satu strategi pertama adalah membagi dokumentasi Anda berdasarkan jenisnya.

Misalnya, Anda biasanya ingin memisahkan dokumentasi pengguna akhir dari dokumentasi perangkat lunak pengembang.

Di dalamnya, Anda juga dapat menggunakan kategori untuk membagi artikel lebih lanjut. Anda dapat menggunakan kategori berdasarkan fitur, kasus penggunaan, add-on, dan sebagainya – apa pun yang masuk akal untuk produk perangkat lunak Anda.

Sesuai dengan contoh Gravity Forms yang sama di atas, Anda dapat melihat bahwa Gravity Forms membagi dokumentasi pengguna akhir berdasarkan tipe fitur.

Fitur lain yang berguna untuk dapat ditemukan adalah saran pencarian langsung. Pengguna dapat mulai mengetik kueri yang relevan ke dalam kotak telusur dan langsung melihat artikel dokumentasi yang cocok dengan kueri tersebut.

Banyak alat dokumentasi menyertakan fungsionalitas pencarian langsung bawaan, termasuk Basis Pengetahuan Heroic.

Selalu Perbarui Dokumentasi Perangkat Lunak Anda

Karena perangkat lunak Anda selalu berubah, dokumentasi perangkat lunak Anda akan selalu dalam proses.

Saat hal-hal berubah dalam perangkat lunak Anda, Anda harus segera memperbarui dokumentasi Anda untuk mencerminkan perubahan tersebut.

Jika tidak, dokumentasi Anda tidak hanya akan "tidak membantu", tetapi dapat benar-benar menimbulkan kebingungan pada pengguna Anda.

Untuk memastikan pembaruan ini terjadi, Anda perlu menugaskan orang tertentu untuk memiliki proses dokumentasi dan pembaruan. Dengan begitu, tidak ada ambiguitas tentang siapa yang bertanggung jawab menjaga semuanya tetap akurat.

Gunakan Umpan Balik Pelanggan Untuk Meningkatkan Dokumentasi Anda

Selain memiliki tim Anda sendiri yang bekerja meninjau dan memperbarui dokumentasi perangkat lunak Anda, Anda juga ingin mempertimbangkan umpan balik pelanggan.

Pelanggan dapat memberikan informasi berharga tentang seberapa membantu (atau berpotensi tidak membantu) artikel dokumentasi perangkat lunak tertentu, beserta detail tentang bagaimana Anda dapat meningkatkannya.

Untuk mengotomatiskan proses umpan balik pelanggan, Anda akan ingin mencari alat manajemen dokumentasi yang menyertakan fitur bawaan untuk umpan balik pelanggan.

Misalnya, plugin Heroic Knowledge Base memungkinkan pengguna menilai sebuah artikel sebagai membantu atau tidak membantu dan juga secara opsional memberikan umpan balik dalam bentuk bebas.

Anda kemudian dapat melihat semua informasi ini dari dasbor untuk menemukan artikel dokumentasi yang perlu Anda tingkatkan dengan cepat.

Mulai Mendokumentasikan Perangkat Lunak Anda Hari Ini

Dokumentasi perangkat lunak membantu Anda dan pelanggan Anda bekerja lebih efektif dan mendapatkan nilai lebih dari perangkat lunak Anda.

Ada berbagai jenis dokumentasi perangkat lunak, jadi Anda perlu memikirkan jenis mana yang sesuai dengan kebutuhan proyek perangkat lunak Anda.

Anda mungkin memiliki dokumentasi yang berbeda untuk tim internal atau eksternal, serta untuk jenis pelanggan yang berbeda, seperti pengembang vs pengguna akhir.

Untuk membuat dokumentasi yang efektif, Anda sebaiknya mengikuti praktik terbaik dari postingan ini.

Untuk menerbitkan dokumentasi tersebut, Anda dapat menggunakan alat sumber terbuka seperti Heroic Knowledge Base, yang didasarkan pada perangkat lunak WordPress yang kuat.

Anda akan mendapatkan fleksibilitas dan kepemilikan platform yang dihosting sendiri, dengan semua fitur dan fungsionalitas yang Anda perlukan untuk menerbitkan dokumentasi perangkat lunak berkualitas tinggi.

Jika Anda ingin mempelajari lebih lanjut, klik di sini untuk pergi ke Basis Pengetahuan Pahlawan.