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


18

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.


3
FYI: Wiki bukan akronim, ini adalah kata Hawaii yang berarti "cepat".
Jörg W Mittag

Fakta bahwa dokumentasi melibatkan binari bukanlah alasan yang baik untuk menghindari menyimpannya dalam sistem kontrol versi Anda. VCS dapat dengan mudah menangani file biner. Dan jika Anda menyimpannya di VCS proyek Anda, Anda memiliki keuntungan untuk dapat melakukan percabangan dokumentasi Anda ketika Anda bercabang proyek Anda.
JW01

Mengenai bekerja offline: Solusi brute-force adalah dengan hanya mengunduh halaman yang Anda inginkan menggunakan pembaca offline. Lebih elegan adalah entah bagaimana mengkloning seluruh wiki, jika praktis (misalnya menyalin database yang mendasarinya dan memiliki instalasi wiki Anda sendiri). Wiki berbasis VCS adalah solusi yang bahkan lebih elegan. Saya sering bekerja offline, dan biasanya hanya mengunduh halaman yang saya butuhkan sudah cukup.
sleske

Jawaban:


16

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.


8

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.


+1 Saya menggunakan Redmine di tempat kerja dan ini benar-benar sistem yang hebat.
Luiz Damim

5

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.


Menarik. Apakah ada perbedaan antara meletakkan dokumen di repositori git dan menyimpan dokumen melalui ikiwiki?
Edison Chuang

1
@Edison Chuang: Tidak, tidak ada. Bahkan, dengan memberikan tiruan dari repositori ikiwiki, Anda dapat mengedit halaman menggunakan editor teks pilihan Anda (Anda tidak harus menggunakan kotak entri teks berbasis browser yang jelek). Anda bahkan dapat memiliki cabang wiki yang berbeda, untuk menyimpan snapshot dokumentasi yang lebih lama atau apa pun.
Greg Hewgill

Kedengarannya seperti dokumen dapat disimpan dalam sistem kontrol versi tanpa masalah meskipun file biner. Pengembang cukup menggunakan alat seperti ikiwiki untuk mengubah halaman wiki menjadi halaman HTML sesuai permintaan.
Edison Chuang

+1 untuk mesin wiki Ikiwiki; yang mesin wiki Hatta adalah ide yang sama untuk repositori Mercurial.
David Cary

ISTR Fitnesse juga menyimpan halaman wiki sebagai file teks, sehingga mereka juga dapat disimpan di sistem kontrol versi Anda jika diinginkan. Walaupun tujuan utamanya adalah pengujian, tidak ada alasan untuk tidak menggunakannya sebagai sistem wiki tujuan umum untuk dokumentasi Anda juga.
Jules

4

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


2

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.


Dan antarmuka yang bagus untuk Mercurial. Dan itu sangat bisa diretas.
Frank Shearar

0

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.


-1

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.

Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.