Target Pemirsa
Saya pikir ketika menjawab pertanyaan ini Anda benar-benar perlu bertanya siapa yang dimaksudkan untuk membaca dokumentasi ini. Pengembang memiliki kebutuhan yang sangat berbeda untuk Pengguna atau bahkan Analis Bisnis.
- Sebagai Pengembang: dokumentasi yang terkait dengan kode yang sedang dipelajari, detail seperti kontrak antarmuka, dan contoh penggunaan. Mungkin beberapa dokumentasi tingkat tinggi, dan spesifikasi protokol untuk ukuran yang baik.
- Sebagai Pengguna: dokumentasi tersedia melalui menu bantuan, atau situs web yang dapat diakses tentang cara menggunakan perangkat lunak.
- Sebagai Analis Bisnis: dokumentasi tersedia sebagai dokumen, atau sebagai situs web yang dapat diakses berguna. Sejumlah kecil detail tentang protokol, arsitektur tingkat tinggi, dan kasus penggunaan adalah yang terbaik.
Pemeliharaan
Ke mana menempatkan sumber untuk dokumentasi ini akan tergantung pada audiens Anda, dan siapa yang menulis untuk audiens Anda.
- Hanya memiliki rumah pengembang? Tempatkan semuanya dalam kode. Ini akan mendorongnya untuk diperbarui. Anda perlu mengerjakan budaya yang mendorong pembaruan dokumentasi sama pentingnya dengan perubahan kode.
- Punya rumah pengembang dan penulis dokumentasi? Bagilah tanggung jawab. Gunakan perkakas berorientasi pengembang untuk pengembang, gunakan perkakas penulis dokumentasi untuk penulis dokumentasi.
Jika memungkinkan pastikan bahwa contoh kode, atau kasus penggunaan dapat dieksekusi. Otomatis eksekusi dan kegagalan flag internal mereka. Kemungkinan halaman ini adalah dokumentasi yang buruk atau buruk.
Selain itu alat apa pun yang Anda pilih untuk menulis dokumentasi Anda, Anda memerlukan cara yang dapat diandalkan untuk mengaitkan versi tertentu dari dokumentasi dengan versi kode yang spesifik. Ini masih menguntungkan bahkan di tanah cloud yang bahagia dengan penyebaran tunggal hijau.
Mengintegrasikan Dokumentasi
Integrasi mungkin diperlukan untuk menghasilkan beberapa dokumentasi, tetapi perhatikan bahwa hanya pengguna yang mengharapkan satu tempat untuk mengakses semua dokumentasi yang mereka butuhkan.
Analis bisnis cukup senang dengan skenario API, spesifikasi desain, dan skenario penggunaan untuk ditempatkan di dokumen terpisah, atau bagian terpisah dari situs web.
Pengembang lebih suka segala sesuatu yang terlihat dari sumbernya, tetapi cukup senang memiliki beberapa dokumen desain tingkat tinggi, dan dokumen spesifikasi protokol terperinci di luar kode, meskipun lebih disukai dalam checkout yang sama.
Kasus Anda
Sejujurnya, dokumentasi di wiki Anda mungkin bukan jenis dokumentasi yang sama dengan basis kode Anda. Mungkin tidak masuk akal untuk menggabungkannya juga.
Di sisi lain, mengintegrasikan keduanya dapat dilakukan dengan beberapa cara sederhana.
- Alat dokumentasi sumber (seperti doxygen) dapat menghasilkan html, dan wiki hidup di server web. Ini akan menjadi titik integrasi sederhana untuk hanya melayani versi yang dibangun bersama wiki dan antar tautan keduanya.
- Beberapa produk wiki akan memungkinkan Anda untuk menjalankan wiki langsung dari file yang dapat Anda laporkan ke basis kode. Ini memberikan perkakas wysiwyg sederhana sambil menjaga dokumentasi dipasangkan dengan kode.
- Format lain seperti pdf dapat diakomodir juga, tetapi ini akan turun ke perkakas khusus yang ingin Anda gunakan. Mungkin masuk akal untuk mengikis wiki Anda menjadi file penurunan harga dan memasukkannya melalui doxygen (atau alat lain). Mungkin masuk akal untuk pdf wiki dan sumber secara terpisah dan menggunakan alat penggabungan pdf.
Pada akhirnya, cari tahu sistem dokumentasi mana yang memiliki biaya perawatan yang rendah, dan membantu Anda dalam memberikan produk berkualitas tinggi seperti yang dilihat oleh audiens Pengembang, Analis Bisnis, dan Pengguna Anda. Apa pun yang menghambat salah satu dari kelompok-kelompok ini tentu akan mengurangi kualitas produk.