Di mana harus meletakkan dokumentasi kode?

Saat ini saya menggunakan dua sistem untuk menulis dokumentasi kode (saya menggunakan C ++):

• Dokumentasi tentang metode dan anggota kelas ditambahkan di sebelah kode, menggunakan format Doxygen. Di server, Doxygen dijalankan pada sumber sehingga hasilnya dapat dilihat di browser web
• Halaman ikhtisar (menggambarkan sekumpulan kelas, struktur aplikasi, contoh kode, ...) ditambahkan ke Wiki

Saya pribadi berpikir bahwa pendekatan ini mudah karena dokumentasi tentang anggota dan kelas sangat dekat dengan kode, sementara halaman ikhtisar sangat mudah diedit di Wiki (dan juga mudah untuk menambahkan gambar, tabel, ...). Peramban web memungkinkan Anda melihat kedua dokumentasi.

Rekan kerja saya sekarang menyarankan untuk meletakkan semuanya di Doxygen, karena kita kemudian dapat membuat satu file bantuan besar dengan semua yang ada di dalamnya (menggunakan Microsoft WorkShop atau Qt Assistant Microsoft). Kekhawatiran saya adalah bahwa mengedit dokumentasi gaya Doxygen jauh lebih sulit (dibandingkan dengan Wiki), terutama ketika Anda ingin menambahkan tabel, gambar, ... (atau apakah ada alat 'pratinjau' untuk Doxygen yang tidak mengharuskan Anda untuk menghasilkan kode sebelum Anda dapat melihat hasilnya?)

Apa yang digunakan proyek sumber terbuka (atau sumber tertutup) besar untuk menulis dokumentasi kode mereka? Apakah mereka juga membagi ini antara gaya Doxygen dan Wiki? Atau apakah mereka menggunakan sistem lain?

Apa cara yang paling tepat untuk mengekspos dokumentasi? Melalui server Web / browser, atau melalui file bantuan besar (beberapa 100MB)?

Pendekatan apa yang Anda ambil saat menulis dokumentasi kode?

Memiliki semua dokumentasi dalam satu sistem, bukan dua, bisa menjadi keuntungan nyata. Hal-hal seperti backup & restore, versi, pencarian global, pencarian & penggantian global, cross-linking, dan, seperti yang Anda tulis, menempatkan semua dokumen dalam satu dokumen akhir, biasanya akan bekerja dengan sedikit "gesekan" ketika Anda tidak harus memiliki dua perbedaan sistem dengan kapabilit yang tumpang tindih.

Di sisi lain, Anda harus berpikir tentang apakah kelebihan ini lebih besar daripada kemudahan Wiki Anda. Lingkaran edit / hasilkan / saring edit / hasilkan lagi mungkin lebih cepat dengan Wiki Anda. Saya kira Anda bisa mendapatkan siklus itu cukup cepat dengan doxygen menjaga halaman tinjauan Anda sebagai sub proyek doxygen terpisah. Anda dapat memanfaatkan kemampuan tautan eksternal doxygen, yang bukan pengganti untuk "pratinjau cepat", tentu saja, tetapi langkah menuju arah itu. Saya belum melakukan ini sendiri, sejauh ini, tetapi saya kira Anda harus mencobanya sendiri jika Anda ingin tahu apakah itu berhasil dalam kasus Anda.

Mengenai proyek lain: Saya pikir alat seperti doxygen terutama untuk dokumentasi perpustakaan. Jika Anda bukan vendor perpustakaan pihak ketiga, dan semua orang yang menggunakan perpustakaan Anda memiliki akses penuh ke kode sumber, maka kebutuhan akan alat seperti doxygen dipertanyakan. Di tim kami, misalnya, kami hampir tidak memiliki dokumen eksternal di luar kode kecuali dokumen pengguna akhir dan dokumen model basis data kami. Alat utama kami untuk dokumentasi semacam itu adalah docbook dan pesolek , yang memberi kami hasil yang memuaskan.

Gunakan Dokumentasi Kode, pertama. Tambahkan Wiki & metode lain, jika memungkinkan

Saya tahu, itu akan sulit, untuk mempertahankannya.

Jawaban praktis:

Secara praktis, hal pertama yang dilakukan pengembang adalah memeriksa kodenya.

Sebagai pengembang, saya suka memiliki dokumentasi eksternal, seperti Wiki, manual. Tapi, hal pertama yang saya lakukan, adalah meninjau kode (kadang-kadang dari pengembang lain, kadang-kadang, saya sendiri).

Sebagai pengembang, yang bekerja di beberapa proyek & pelanggan, saya melakukan mungkin untuk menambahkan dokumentasi eksternal, tetapi, umumnya memiliki banyak beban kerja, dan tidak dapat mendukung wiki.

Terkadang, manajer proyek, & bos lain, tidak peduli tentang dokumentasi, terkadang pengembang lain tidak.

Dan, yang terbaik yang bisa saya lakukan, adalah menambahkan beberapa komentar ke kode.

Semoga berhasil

Beberapa menggunakan sistem lain - lihat Sphinx Python misalnya, mereka memiliki sistem dokumen all-in-one yang membangun semuanya (ini juga berfungsi untuk C / C ++)

Saya selalu menganggap dokumentasi sebagai terpisah dari kode, doxygen bagus, tetapi untuk tinjauan umum API, bukan 'dokumentasi'. Untuk itu, wiki sangat bagus, tetapi saya lebih suka menggunakan ASCIIDOC dan menyimpan hasilnya dalam kontrol sumber bersama dengan kode, terutama karena saya dapat menghasilkan PDF dari itu untuk diserahkan kepada orang lain (mis. Penguji, pelanggan, dll)

Doxygen memungkinkan Anda membuat halaman wiki, HTML, HTML, hampir semua yang dapat Anda pikirkan.

Preferensi pribadi saya adalah memiliki Doxygen dan wiki dan skrip atau sesuatu untuk memeriksa ketika mereka berbeda.

Karena versi 1.8.0 doxygen mendukung Markdown , yang seharusnya membuat pengalaman menulis halaman statis sama nyamannya dengan di sistem Wiki.

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.

Jika Anda menggunakan ASCII, Anda harus menyimpan menyembunyikan data dokumentasi Anda di bagian atas kode sumber Anda! Maka hanya pengguna yang paling pintar (baca: layak) yang memiliki kesempatan untuk menggunakan dokumen Anda.

Memiliki dokumentasi dalam format portabel yang terdefinisi dengan baik, mudah diekspor, mungkin merupakan keuntungan nyata. Jika sphinx mati (tidak mungkin) saya hanya perlu mengonversi ke sistem lain, yang saya kira akan menjadi tugas skrip. Memindahkan data dari wiki (mungkin disimpan dalam basis data dalam format kepemilikan mungkin menyusahkan).