Wiki yazılım geliştirme için belgeleri saklamak için gerçekten uygun mudur? [kapalı]


18

Herkes iyi belgelenmiş yazılım geliştirmenin başarıya yol açtığını bilir. Ancak, genellikle UML diyagramı gibi belgede yalnızca düz metinlerin değil ikili içeriğin de yer alacağı anlamına gelir. Birçok insanın bunu söylediğini duydum. Sürüm kontrol sistemi ikili dosyalar için uygun bir yer değildir. Bu konuyu tamamen anlıyorum ve kabul ediyorum. Birkaç tecrübeli geliştiriciye belgeleri depolamak için en iyi yerin nerede olması gerektiğini sordum ve aldığım cevap "wiki" idi. Wiki iyi ama başka bir potansiyel konuyu düşündüm. Bir sürüm kontrol sisteminde depolanan kaynak kodu, wiki'deki ilgili dokümanına nasıl bağlanabilir? Birisinin git veya mercurial deposunu klonladığını varsayalım. Belgeyi kolayca nasıl bulabilir? Yoksa bir şey mi kaçırdım?

Bazı wiki sistemlerinin kaynak kontrol sistemleriyle entegre olabileceğini biliyorum. Ama benim endişem entegrasyon yeteneği ile ilgili değil. Bir git deposundan kaynak kodunu klonladıysanız ve bir süre sonra bir trene bindiğinizde ve trende çevrimdışı çalışmaya devam etmek istiyorsanız (DVCS'nin büyük bir özelliğidir). Sonra aniden trende çevrimdışı çalıştığınız için belgeye erişiminizin olmadığını anlarsınız. Öte yandan, belge git deposunda saklanmışsa, depo klonlanmış belgeye erişebilirsiniz.


3
FYI: Wiki bir kısaltma değil , "çabuk" anlamına gelen Hawaii dili bir kelime.
Jörg W Mittag

Belgelerin ikili dosyaları içermesi, sürüm kontrol sisteminizde saklamaktan kaçınmak için gerçekten iyi bir neden değildir. VCS'ler ikili dosyalarla kolayca başa çıkabilir. Ve projenizin VCS'sinde saklarsanız, projenizi şubeye koyduğunuzda belgelerinizi bölümlere ayırma avantajına sahip olursunuz.
JW01

Çevrimdışı çalışmaya gelince: Kaba kuvvet çözümü, sadece çevrimdışı okuyucu kullanarak istediğiniz sayfaları indirmektir. Daha zarif, eğer varsa, tüm wiki'yi bir şekilde klonlamaktır (örneğin, temel veritabanını kopyalayın ve kendi wiki kurulumunuzu yapın). VCS tabanlı wiki'ler daha da zarif bir çözümdür. Sık sık çevrimdışı çalışıyorum ve genellikle düzenli olarak ihtiyacım olan sayfaları indirmek yeterli.
sleske

Yanıtlar:


16

WIKI, yazılım geliştirmek için belge depolamak için gerçekten uygun mu?

Dokümanlar, pdf'ler ve diğer tür dosyaları yazmak yerine, WIKI'nin bir işbirliği aracı olarak tam potansiyelini neden ortaya çıkarmıyorsunuz? Belgelerinizi oraya yazabilir, diyagramlarınızı ekleyebilir ve daha da iyisi: Fitnesse kullanıyorsanız , wiki sayfalarınızı yürütülebilir bir özellik haline gelebileceğinden gerçekten kullanışlı ve canlı belgelere dönüştürebilirsiniz.

Herkes, iyi belgelenmiş yazılım geliştirmenin başarıya yol açtığını biliyor

Buna dikkat et. Belgeler, bok kodunu iyi olana dönüştürmeyecekleri için BAŞARIYOR. Ancak belgeler başarılı yazılımlara giden yolun bir parçasıdır. Ama sadece bir kısmı ve iyi uygulamaların ve iyi insanların yerini almayacaklar.


8

Birden fazla cevap Trac'i bir öneri olarak gösterdiğinden, benzer, ancak bence daha iyi bir alternatif önermek istiyorum: Redmine .

Redmine, Wiki, Belge Deposu ve sürüm kontrolü entegrasyonunu içeren bir proje yönetimi çözümüdür. Ayrıca Ruby on Rails ile yazılmış ve benim deneyimime göre Trac'den daha geniş ve kesmek daha kolay.

Her şeyden çok, kullanımı gerçekten çok kolay ve ekibi kullanmak çok kolay.

Özellikleri:

  • Birden fazla proje desteği
  • Esnek rol tabanlı erişim kontrolü
  • Esnek sorun izleme sistemi
  • Gantt şeması ve takvim
  • Haber, belge ve dosya yönetimi
  • Özet akışları ve e-posta bildirimleri
  • Proje başına wiki
  • Proje forumları başına
  • Zaman takibi
  • Sorunlar, zaman girişleri, projeler ve kullanıcılar için özel alanlar
  • SCM entegrasyonu (SVN, CVS, Git, Mercurial, Bazaar ve Darcs)
  • E-posta yoluyla sorun oluşturma
  • Birden çok LDAP kimlik doğrulama desteği
  • Kullanıcı kendi kendine kayıt desteği
  • Çok dilli destek
  • Birden çok veritabanı desteği

Çevrimdışı ihtiyaçlarınız için, sürüm kontrolünü tasarım belgeleriyle karıştırmak fikrinden hoşlanmıyorum. Eminim bunu sormak için nedenleriniz var, ama gerçekten ne sıklıkta çevrimdışısınız ve tasarım belgelerine erişmeniz gerekiyor? Şansı bu gerçekten bir köşe vakası.


+1 Redmine'ı işte kullanıyorum ve gerçekten harika bir sistem.
Luiz Damim

5

Bazı wiki'ler (ör. Ikiwiki ), belirttiğiniz gibi verilerini Git'te saklayabilir. Bununla birlikte, belgeleri normal kaynak deponuzun altında Git alt modülü olarak bağlayabilirsiniz .

Yukarıdaki kurulumda, kaynağı çekmek ve alt modülleri güncellemek belgelerin en son kopyasını çekecektir. Çevrimdışı olarak, her birini istediğiniz zaman düzenleyebilirsiniz. Bir ağa döndüğünüzde, her ikisi de kullandığınız paylaşılan konuma geri itilebilir.

Bunun garip kısmı, dokümantasyon her güncellendiğinde (Ikiwiki web arayüzü üzerinden bile), Git kaynak deposundaki ilgili alt modülü de güncellemeniz gerektiğidir. Ancak bu kolayca otomatikleştirilebilir.


İlginç. Belgeyi git deposuna koymak ve belgeyi ikiwiki ile saklamak arasında bir fark var mı?
Edison Chuang

1
@Edison Chuang: Hayır, yok. Aslında, ikiwiki deposunun bir kopyası verildiğinde, istediğiniz metin düzenleyicisini kullanarak sayfaları düzenleyebilirsiniz (tarayıcı tabanlı bir metin giriş kutusu kullanmanız gerekmez). Eski belgelerin veya başka herhangi bir şeyin anlık görüntüsünü tutmak için wiki'nin farklı dallarına bile sahip olabilirsiniz.
Greg Hewgill

İkili dosyalar olsa bile, belge herhangi bir sorun olmadan sürüm kontrol sisteminde saklanabiliyor gibi görünüyor. Geliştirici, wiki sayfalarını istek üzerine HTML sayfalarına dönüştürmek için ikiwiki gibi araçları kullanabilir.
Edison Chuang

Ikiwiki wiki motoru için +1; Hatta wiki motoru Mercurial depoları için de benzer bir fikirdir.
David Cary

ISTR Fitnesse ayrıca wiki sayfalarını metin dosyaları olarak saklar, böylece isterseniz sürüm kontrol sisteminizde de saklanabilirler. Birincil amaçları test ederken, bunu dokümanlarınız için de genel amaçlı bir wiki sistemi olarak kullanmamanız için hiçbir neden yoktur.
Jules

4

Belgeleri kaynak koduyla aynı depoda saklamak mantıklıdır. Sfenks benim için iyi bir seçenek gibi görünüyor.

  • reStructuredText dosyalarını girdi olarak alır , bu da düzenlemek ve fark etmek kolaydır
  • köprü bağlantılı çıktı üretir (HTML, PDF, ...)
  • kaynak kodunuza başvurabilirsiniz (Python, C, C ++, JavaScript)


0

Çevrimdışı çalışmaya uymaya çalışmam. Herkes için birlikte çalışmayı en kolay hale getiren kaynağı kullanırdım. Örneğin, PHP kodu yazıyorsanız, PHPDocumentor tarafından oluşturulabilen satır içi belgeleri kullanmanızı öneririm . Her yerde üretilebilir ve Trac için bir eklenti vardır . Daha sonra çevrimiçi veya kapalı, belgelere oldukça hızlı bir şekilde erişebilirsiniz.

Anahtar kullanılabilirlikle ilgilidir. Bakımı zorsa, acı çekmeye başlayacaktır. Acı çekmeye başladığında, dokümantasyon kalitesi düşer. Bu olduğunda, insanlar şikayet etmeye başlar ve sonra her şey yokuş aşağı gider.


-1

Belgeleri saklamak için wiki kullanmak benim için çok anlamlı.

Veracity , wiki içeriğinin ve kaynak kodunun daha sıkı entegrasyonuna izin veren bir DVCS örneğidir.

Sitemizi kullandığınızda şunları okuyup anladığınızı kabul etmiş olursunuz: Çerez Politikası ve Gizlilik Politikası.
Licensed under cc by-sa 3.0 with attribution required.