Apakah wiki benar-benar sesuai untuk menyimpan dokumen untuk pengembangan perangkat lunak? [Tutup]

Semua orang tahu bahwa pengembangan perangkat lunak yang terdokumentasi dengan baik mengarah pada kesuksesan. Namun, itu biasanya berarti bahwa tidak hanya teks biasa tetapi juga konten biner akan terlibat dalam dokumen, seperti diagram UML. Dan saya pernah mendengar banyak orang mengatakan itu. Sistem kontrol versi bukan tempat yang tepat untuk file biner. Saya benar-benar mengerti dan setuju dengan masalah ini. Saya bertanya kepada beberapa pengembang berpengalaman di mana tempat terbaik untuk menyimpan dokumen dan jawaban yang saya dapatkan adalah "wiki". Wiki bagus tapi saya menganggap masalah potensial lain. Bagaimana kode sumber yang telah disimpan dalam sistem kontrol versi dapat terhubung ke dokumen terkait di wiki? Katakanlah seseorang mengkloning repositori git atau mercurial. Bagaimana dia bisa menemukan dokumen dengan mudah? Atau apakah saya baru saja melewatkan sesuatu?

Saya tahu beberapa sistem wiki memiliki kemampuan untuk berintegrasi dengan sistem kontrol sumber. Tetapi kekhawatiran saya bukan tentang kemampuan integrasi. Jika Anda telah mengkloning kode sumber dari repositori git dan setelah beberapa saat Anda naik kereta dan ingin terus bekerja offline di kereta (yang merupakan fitur besar DVCS). Kemudian Anda tiba-tiba menyadari bahwa Anda tidak memiliki akses ke dokumen karena Anda bekerja offline di kereta. Di sisi lain, jika dokumen disimpan di repositori git Anda akan memiliki akses ke dokumen dengan repositori yang dikloning.

Apakah WIKI benar-benar tepat untuk menyimpan dokumen untuk pengembangan perangkat lunak?

Alih-alih menulis dokumen, pdf, dan jenis file lainnya, mengapa Anda tidak melepaskan potensi penuh WIKI sebagai alat kolaborasi? Anda dapat menulis dokumen di sana, melampirkan diagram Anda dan bahkan lebih baik lagi: jika Anda menggunakan Fitnesse , Anda dapat mengubah halaman wiki Anda menjadi dokumentasi yang sangat berguna dan hidup, karena dapat menjadi spesifikasi yang dapat dieksekusi.

Semua orang tahu bahwa, pengembangan perangkat lunak yang terdokumentasi dengan baik mengarah pada kesuksesan

Hati-hati dengan yang ini. Dokumen TIDAK AKAN MENUJU KEBERHASILAN, karena mereka tidak akan mengubah kode sampah menjadi yang baik. Tetapi dokumen adalah bagian dari jalan menuju perangkat lunak yang berhasil. Tetapi hanya sebagian dan mereka tidak akan menggantikan praktik baik dan orang baik.

Karena beberapa jawaban menunjuk ke Trac sebagai saran, saya ingin menyarankan yang serupa, tetapi lebih baik menurut saya, alternatif: Redmine .

Redmine adalah solusi manajemen proyek, termasuk Wiki, Document Repository, dan integrasi kontrol versi. Ini juga ditulis dalam Ruby on Rails dan cara yang lebih mudah untuk memperpanjang dan meretas daripada Trac, menurut pengalaman saya.

Lebih dari segalanya itu sangat mudah digunakan dan mudah untuk membuat tim menggunakannya.

Fitur:

• Dukungan banyak proyek
• Kontrol akses berbasis peran fleksibel
• Sistem pelacakan masalah yang fleksibel
• Gantt chart dan kalender
• Berita, dokumen & manajemen file
• Umpan & pemberitahuan email
• Per proyek wiki
• Per forum proyek
• Pelacakan waktu
• Bidang khusus untuk masalah, entri waktu, proyek, dan pengguna
• Integrasi SCM (SVN, CVS, Git, Mercurial, Bazaar, dan Darcs)
• Masalah pembuatan melalui email
• Beberapa dukungan otentikasi LDAP
• Dukungan registrasi mandiri pengguna
• Dukungan multi bahasa
• Dukungan banyak basis data

Untuk kebutuhan offline Anda, saya tidak suka gagasan mengacaukan kontrol versi dengan dokumen desain. Saya yakin Anda memiliki alasan untuk menanyakan hal ini, tetapi seberapa sering Anda offline dan memerlukan akses ke dokumen desain? Kemungkinannya ini benar-benar kasus sudut.

Beberapa wiki (mis. Ikiwiki ) memiliki kemampuan untuk menyimpan data mereka di Git, seperti yang Anda sebutkan. Oleh karena itu, Anda dapat menautkan dokumentasi sebagai submodule Git di bawah repositori sumber reguler Anda.

Dengan pengaturan di atas, menarik sumber dan memperbarui submodul akan menarik salinan dokumentasi terbaru. Offline, Anda dapat mengedit masing-masing sesuka hati. Saat Anda kembali ke jaringan, keduanya dapat didorong kembali ke lokasi berbagi apa pun yang Anda gunakan.

Bagian yang aneh dari ini adalah bahwa setiap kali dokumentasi diperbarui (bahkan melalui antarmuka web Ikiwiki), Anda juga perlu memperbarui submodul yang sesuai dalam repositori sumber Git. Namun, ini dapat dengan mudah diotomatisasi.

Masuk akal untuk menyimpan dokumentasi dalam repositori yang sama dengan kode sumber. Sphinx sepertinya pilihan yang bagus untuk saya.

• dibutuhkan file reStructuredText sebagai input, yang mudah diedit dan dif
• ini menghasilkan output hyperlink (HTML, PDF, ...)
• Anda dapat referensi kode sumber Anda (Python, C, C ++, JavaScript)

Trac menyediakan antarmuka ke Subversion, Wiki yang terintegrasi, dan fasilitas pelaporan yang nyaman. http://trac.edgewall.org/
Tapi saya tidak tahu tentang tumpukan yang Anda instal.

Saya tidak akan mencoba menyesuaikan diri dengan pekerjaan offline. Saya akan menggunakan sumber daya yang paling mudah digunakan untuk semua orang. Misalnya, jika Anda menulis kode PHP, saya sarankan menggunakan dokumentasi sebaris yang dapat dihasilkan oleh PHPDocumentor . Itu dapat dihasilkan di mana saja dan ada plugin untuk Trac . Kemudian online atau tidak aktif, Anda memiliki akses ke dokumentasi, juga cukup cepat.

Kuncinya adalah tentang kegunaan. Jika sulit dipertahankan, ia akan mulai menderita. Ketika mulai menderita, kualitas dokumentasi turun. Ketika itu terjadi, orang-orang mulai mengeluh dan kemudian semuanya menjadi menurun.

Menggunakan wiki untuk menyimpan dokumentasi sangat masuk akal bagi saya.

Veracity adalah contoh dari DVCS yang memungkinkan integrasi yang lebih ketat dari konten wiki dan kode sumber.