Haruskah Git digunakan untuk dokumentasi dan manajemen proyek? Haruskah kode berada di repositori terpisah?

68

Saya memulai repositori Git untuk proyek grup. Apakah masuk akal untuk menyimpan dokumen dalam repositori Git yang sama dengan kode - sepertinya ini bertentangan dengan sifat alur revisi git.

Berikut ringkasan pertanyaan saya:

  • Apakah gaya revisi Git akan membingungkan jika kedua kode dan dokumen diperiksa ke dalam repositori yang sama ? Pengalaman dengan ini?

  • Apakah Git cocok untuk kontrol revisi dokumentasi?

  • Saya TIDAK bertanya apakah Sistem Kontrol Revisi secara umum harus atau tidak boleh digunakan untuk dokumentasi - seharusnya.

Terima kasih atas responnya sejauh ini!

git version-control project-management EmpireJones
sumber
Ah, oke ... terima kasih atas klarifikasi. Saya tidak mengerti mengapa itu menjadi masalah, tapi saya tidak punya pengalaman pribadi dengan GIT (hanya pemahaman teoretis), jadi saya akan membiarkan seseorang dengan pengalaman lebih langsung menjawab pertanyaan itu.
Flimzy
1
Saya tidak begitu mengerti bagaimana ini pada topik. Anda sedang berbicara tentang dokumentasi perangkat lunak dan melakukan dengan DVCS
Tim Post
Mungkin tergantung pada dokumentasi dan kebutuhan Anda. Apakah Anda memerlukan diff dan apakah itu dalam format yang dapat mengatasinya? Jika git memberikan layanan yang diperlukan, pasti. Beats memiliki sistem manajemen dokumen terpisah ...
Rig
Jika dokumentasi Anda dalam teks biasa - baik saja. Jika ini adalah format biner, Anda pada dasarnya memerlukan sistem kontrol versi yang memahami format biner - ini adalah penguncian vendor dalam bentuk paling murni.
terkait: Apa Bagian dari Proyek Anda Seharusnya dalam Kontrol Kode Sumber?
nyamuk

Jawaban:

53

Kami menyimpan dokumentasi di SVN sepanjang waktu. Bahkan, seluruh panduan pengguna kami ditulis dalam LaTeX, dan disimpan dalam SVN. Kami memilih LaTeX secara khusus karena merupakan bahasa berbasis teks, dan mudah untuk menunjukkan perbedaan baris per baris.

Kami juga menyimpan beberapa file berformat non-teks, seperti file .doc Microsoft Office, spread sheet, file .zip, dll, bila perlu ... tetapi beberapa manfaat RCS hilang ketika Anda tidak dapat melihat tambahannya beda.

Kuncinya adalah memastikan dokumentasi Anda tertata dengan baik, sehingga orang-orang dapat menemukan (dan memperbarui) dokumentasi (dan sumbernya) ketika mereka membutuhkannya.

Flimzy
sumber
11
Jika Anda seorang toko Microsoft, TortoiseSVN mendukung MS Office baris demi baris.
Phil
2
Menjatuhkan format dokumen biner akan membuat dunia menjadi tempat yang lebih baik. o mengingat bahwa dokumen adalah teks biasa, seharusnya tidak ada masalah nyata dengan DVCS.
Kai Inkinen
Oh, dan pertama kali saya mendengar tentang TortoiseSVN dan file doc, jadi +1 untuk itu. Bertanya-tanya apakah itu akan berakhir di Tortoise [AnyDVCS] kapan saja di masa depan.
Kai Inkinen
@ Phil: Bagaimana TortoiseSVN mencapai ini? Apakah penampil doc-diff terintegrasi dengan klien SVN, atau dapatkah digunakan secara independen?
Flimzy
1
Opsi keren adalah menggunakan Pandoc sehingga sebagian besar dokumentasi Anda ada di Markdown, tetapi bit-bit penting masih bisa menggunakan TeX. Karena mengkompilasi Markdown ke LaTeX, hasilnya terlihat sama. Namun, ini juga akan memungkinkan Anda mengekspornya ke format yang berbeda dan akan membuat sumber lebih mudah dibaca.
Tikhon Jelvis
22

Baik itu tergantung pada format apa yang Anda gunakan untuk dokumentasi. Jika itu adalah sesuatu yang berbasis teks itu semua baik.

Git juga dapat menyimpan konten biner dan Anda dapat melacak revisi, tetapi output diff tidak masuk akal.

Dimungkinkan juga untuk menyimpan dokumentasi dalam kode itu sendiri seperti perldoc pod, java juga memiliki beberapa format / anotasi untuk ini.

cstamas
sumber
Saya setuju, walaupun dimungkinkan untuk menyimpan dokumentasi non-teks, git akan jauh lebih baik jika Anda menyimpan teks. Sudah ada pembicaraan tentang pengandar diff yang tahu bagaimana cara membedakan kata (atau serupa) dokumen, tapi saya tidak yakin apakah itu diterapkan atau tidak
Sverre Rabbelier
Saya pikir Word memindahkan format mereka dari biner ke XML.
cledoux
3
@ karategeek6 Format 'XML' Word tidak dapat dibaca oleh manusia. Dan satu baris teks tidak sesuai dengan satu baris XML Word, bahkan dalam perkiraan. Jadi mungkin juga biner.
Anda dapat menginstruksikan Word untuk menyimpan hasil Anda dalam XML yang tidak terkompresi. Pilih Save As, lalu pilih Word XML Document (*.xml)sebagai ganti default Word Document (*.docx). XMLnya cukup rumit, jadi ini bukan jaminan perubahan akan mudah dibaca, tapi setidaknya tidak akan biner.
Kyralessa
> tetapi output diff tidak masuk akal. Jika berbeda, kita dapat membuka 2 revisi dokumen berdampingan dan membandingkannya dengan mata kita :)
Luke
14

Saya tidak dapat membayangkan mengapa Anda berpikir mungkin ada masalah menggunakan git, atau sistem kontrol versi lainnya, untuk dokumentasi. Sama seperti kode sumber, dokumentasi harus memiliki riwayat lengkap dan kemampuan untuk kembali ke versi sebelumnya jika itu diperlukan. Sistem kontrol versi sangat cocok untuk ini.


sumber
6
Hanya jika dokumentasinya dalam bentuk teks. Gumpalan biner tidak sepenuhnya mendapat manfaat dari kontrol versi.
2
@ ThorbjørnRavnAndersen: Meski begitu, kecuali Anda memiliki sistem versi biner khusus, mungkin lebih baik menyimpan file biner di Git daripada sendiri.
Tikhon Jelvis
@TikhonJelvis Saya tidak mempertanyakan apakah itu ide yang baik untuk meletakkan file biner di git - jika mereka adalah artefak asli, itu benar. Namun, cobalah untuk menjalankan "git diff" pada dokumen Word.
@ user1249: Anda dapat "mengekspor" 2 revisi ke desktop, katakanlah my_docs_rev15.docx dan my_docs_rev14.docx lalu buka berdampingan dan bandingkan dengan mata dan otak Anda, itu tidak terlalu sulit :)
Luke
14

Jelas bahwa menggunakan semacam Sistem Kontrol Versi untuk menyimpan dokumen adalah hal yang mulia. Bagian yang lebih menarik dari pertanyaan ini adalah apakah ada baiknya menyimpan dokumen di lokasi SAMA sebagai kode sumber? Masalah yang mungkin terjadi di sini adalah bahwa mungkin sulit untuk menetapkan hak akses yang berbeda untuk kode dan dokumentasi dalam kasus itu. Dan dalam banyak kasus bisnis orang akan membutuhkan akses ke dokumen tetapi bukan kode sumber, seperti departemen pemasaran atau BA.

Ma99uS
sumber
3
Ya, aspek "lokasi yang sama" adalah salah satu bagian penting dari pertanyaan ini!
Lokasi yang sama baik jika Anda bisa mengelolanya, karena itu menghindari kebutuhan untuk memiliki pengetahuan suku (mengetahui ke mana harus mencari), atau kebutuhan untuk pergi mencari di mana barang-barang itu.
cepat_now
Mereka mungkin tidak memerlukan akses ke kode tetapi tidak ada salahnya bagi mereka untuk memiliki akses itu. Mereka tidak harus melihatnya. Rahasia umumnya tidak seharusnya dalam kontrol versi.
bdsl
9

Di perusahaan tempat saya bekerja kami menempatkan dokumentasi di SVN. Namun, setelah beberapa konflik dan kebutuhan untuk membaginya, kami memutuskan untuk memindahkannya ke Mediawiki.

Awalnya itu trac, setelah itu pindah ke Mediawiki karena lebih mudah untuk menggunakan ...

Masalah utama dengan SVN adalah penyebab berbagi kami memiliki sistem otorisasi untuk SVN.

confiq
sumber
2
Bukankah maksud Anda Mediawiki, mesin wiki yang digunakan Wikipedia?
@ Martijn, saya berasumsi begitu
Teo Klestrup Röijezon
@ Martijn: Ya, diedit
confiq
Saya lebih suka tetap dengan wiki daripada mengirim banyak file yang tidak tentu ke SCM, tapi itu lebih berkaitan dengan preferensi pribadi. Ada banyak lagi yang bisa Anda lakukan dengannya. Saya khusus suka Foswiki dan template berbasis situs web / proyek mereka. Senang seseorang menunjuk memutuskan untuk menggunakan wiki karena masalah :) +1.
Oeufcoque Penteano
9

  • Memiliki lebih dari sekadar kode sumber dalam repositori adalah hal yang sangat bagus.

    Ini mengelompokkan semua sumber daya Anda bersama-sama dan mengubah proyek menjadi entitas yang terpusat dan kohesif daripada kumpulan file yang tersebar. Kontributor / karyawan tahu di mana menemukan segalanya, daripada mengirim "Di mana saya mengubah dokumentasi untuk fitur x?" email.

    Anda akan ingin mengatur segalanya. Memiliki sistem untuk memisahkan srcdari imagesdari docs. Anda selalu dapat menambahkan .gitignoreke direktori untuk menjaga repositori dan riwayat bersih. Karena Git berkomitmen berbasis file, * Anda dapat memisahkan perubahan sumber dari perubahan dokumentasi sekuat yang Anda mau.

  • Seperti yang orang lain katakan, Git bagus untuk versi dokumentasi selama itu berbasis teks.

  • Saya sangat setuju; dokumentasi harus diversi tepat di samping kode.

Kredibilitas saya berasal dari menjadi pengguna GitHub dan berkontribusi pada satu proyek dan menjelajahi banyak proyek lainnya. Dalam pengalaman saya, proyek yang lengkap dan terpadu mudah untuk diketahui dari yang tidak ada. Saya mencoba untuk memuat semua proyek saya dalam direktori tunggal bila memungkinkan.

* Ini tidak cukup akurat, karena ada cara untuk menentukan bagian dari file yang akan dikomit ( inilah salah satu contoh ).

Tyler Wayne
sumber
4

Saya datang ke sini dengan pertanyaan serupa. Kami berasal dari lingkungan SVN, di mana pada dasarnya adalah no-brainer untuk menyimpan semua materi yang terkait dengan proyek dalam repositori yang sama. Karena sifat SVN, Anda dapat dengan mudah memeriksa bagian-bagian repositori, jadi jika Anda hanya perlu kode sumber (misalnya, penyebaran situs web), itu tidak masalah.

Dengan Git, segalanya berbeda. Sebuah checkout selalu berada di level root, jadi jika Anda ingin meletakkan semuanya di repositori yang sama, Anda akan selalu berakhir dengan struktur direktori yang sama. Salah satu pendekatan yang saya temui adalah meletakkan segala sesuatu di cabang terpisah, yaitu Anda memiliki kode-cabang (yang biasanya akan menjadi master normal Anda, mengembangkan, dll cabang) dan cabang doc, yang memiliki sendiri, struktur direktori terpisah. Saya belum yakin itu ide terbaik, tetapi itu adalah saran yang menghindari masalah yang saya bayangkan adalah dasar dari pertanyaan Anda.

Eelke Blok
sumber
Cabang yang berbeda dengan struktur direktori yang sangat berbeda memiliki bau kode yang sangat buruk bagi saya. Saya akan meninggalkan semuanya dalam satu repo, membuatnya mudah bagi kontributor untuk lebih mudah menambahkan campuran kode dan dokumentasi. Bahkan, pemrograman melek (Google itu!) Menuntutnya.
tbc0
Saat mendistribusikan paket, saya sebagian dengan gaya .deb yang memungkinkan saya untuk mengunduh file yang dapat dieksekusi ke semua server, sementara kotak pengembangan saya juga memiliki paket dokumentasi.
tbc0
1

Saya menggunakan wiki untuk dokumen internal ... dapatkan revisi PLUS akses menonjol / pengeditan mudah. Ketika dokumentasi tidak sinkron, perbarui saat itu juga. Untuk dokumentasi pengguna akhir, pertimbangkan alat profesional seperti Madcap Flare Mereka menggunakan dialek XML untuk berbagi, menyusun, dan mengubah dokumentasi.

Michael Brown
sumber
-1

Dalam kode, pikiran biasanya dipisahkan baris demi baris. Saya cenderung menulis dokumentasi dengan soft line wraps. Ketika saya mengkomit file-file itu, baris panjang paragraf. Itu tidak terlalu berguna untuk dibaca git diff. Itulah masalah yang saya coba selesaikan ketika saya mencari di Google dan menemukan halaman ini. Terima kasih kepada Arne Hartherz karena telah memperkenalkan saya git diff --word-diff. Anda mungkin lebih suka git diff --color-words.

tbc0
sumber