Açık kaynak kodlu bir projenin belgeleri nasıl yönetilir? [kapalı]

Büyüyen bir açık kaynak projesinin yaratıcısıyım. Şu anda, belgeleri yönetmenin en iyi yolunu bulmaya çalışıyorum. İşte düşündüğüm seçenekler:

• HTML Web Sitesi
• Bir Github Wiki
• Github'da Barındırılan Markdown Dosyaları
• Tüm Belgeleri Github'a Yerleştirme README.md

Belgeler zaten Markdown'da yazılmış, nasıl kullanılabilir hale getirmek istediğimi anlayamıyorum. Belgeleri kaynağa dayandırabildiğim ve etiketleyebildiğim gibi belgelendirebildiğim ve etiketleyebildiğim için Git'e doğru çekildim.

Markdown'ı HTML'ye çevirmek ve tarz bir web sitesinde görüntülemek için bir Markdown kütüphanesi kullanabilirim. Bir değişiklik olduğunda web sitesine değişiklikleri yüklemem gerekecek ve belgelerin tüm farklı "etiketlerini" yönetmek zor olacaktır.

Github Wikis (bildiğim kadarıyla) bulunduğunuz şubeye göre değişmez. Böylece, herhangi bir zamanda Github Wiki formundaki belgelerin yalnızca "ana" versiyonuna sahip olabilirim.

Hepsini Github README'ye koymak biraz temiz. Dallanma ve etiketleme alıyorum, ancak kullanımı biraz yorucu ve kolay navigasyona iyi borç vermiyor.

Müthiş bir çözüm eksik mi? Başka hangi seçeneklerim var?

Söyleyeceğim bir şey belgelerin kaynak kodu dosyalarında (istediğiniz herhangi bir biçimlendirme kullanarak) ve daha sonra bunlardan otomatik olarak oluşturulan dokümanlar OLMALIDIR.
En azından sitenizde, kaynak paketin bir parçası olarak dokümanların biçimlendirilmiş indirmelerini oluşturabilirsiniz, böylece kullanıcının belirli bir belge aracına ihtiyacı yoktur

Başka birinin bir işlevi düzeltme / ekleme ve daha sonra hemen aynı dosyaya bitişik bir parça biçimlendirme belgesi ekleme / ekleme şansı düşük olabilir, ancak aynı işlemi yapmak için farklı bir belge deposunda tamamen farklı bir dosya bulma şansı biraz Sıfırdan daha az.

İsterseniz her zaman büyük metin blokları içeren bir tutorial.h dosyasına sahip olabilirsiniz - ancak kaynağın bir parçası olarak ele alın

Projeniz bir kütüphane ise, kodun içindeki yorumlardan API sözdizimini belgelemek için hiçbir şey javadoc tarzı belgeleri yenemez.

Öğreticiler, kullanım örnekleri vb. Dokümantasyon konusunda wiki formatı kullanmanızı şiddetle tavsiye ederim. Gördüğüm diğer projelerin farklı şubeler için ayrı sayfaları var. Yeni bir şubeye başladığınızda, yeni bir sayfaya geçmemiş olan şeyleri kopyalayıp oradan güncelleme yaparsınız.

Bir wiki tavsiye için benim neden anekdot, ama kişisel deneyim. Açık kaynak projelerine çeşitli vesilelerle dokümantasyon güncellemelerine katkıda bulundum, ancak hepsi wiki'de. Bir şey bulmaya çalışıyorsam ve belgeler yanıltıcı veya yararsızsa, anladıktan sonra dokümanlardayken wiki'yi güncelleyeceğim ve aklımda taze. Geri verme duygusundan uzak değilse, en azından bir ya da iki yıl içinde kendime tekrar bakmam gerektiğini biliyorum.

Bir wiki yoksa, girişin önündeki engel, belgelerin nasıl oluşturulduğunu, nerede depolandığını, kaynak kontrolünden en sonuncuyu alma, düzenlemeleri yapma, gerçek düzenlemeleri yapma ve bir yama kabul etmek için posta listelerinde gezinmek.

Belgeleriniz üzerinde sıkı kontrol istiyorsanız, elbette sizin için en rahat olanı kullanın, çünkü çoğunlukla güncelleyen tek kişi siz olacaksınız. Topluluk katılımını teşvik etmek istiyorsanız, bir wiki kullanın.

Kaynak ile Barındırılan Markdown Dosyaları Son derece iyi çalışıyor.

Örneğin RST tabanlı docutils araçları, bir belge kümesinden HTML veya LaTex (ve PDF'ler) oluşturabilir.

Bu - aslında - seçenek 1 ve seçenek 3'ü birleştirir.

Belgeleri Markdown'dan reStructuredText'e dönüştürmenin sakıncası yoksa, Sfenks'i düşünün . Markdown kadar kolay, ama çok daha güçlü.