Çok dilli yazılım projelerinde dokümantasyon birleştirme yöntemleri değerlendirildi
Öne çıkanlar
- Dönüştürme yöntemi araçların yerel arama mantığını yok ediyor ve derleme süresini uzatıyor.
- Breathe aracı kaldırılınca pigweed.dev dokümantasyon derleme süresi 90 saniyeden 60 saniyeye düştü.
- Pagefind kütüphanesi farklı araçlardan çıkan statik HTML sayfalarını tek bir arama dizininde birleştirdi.
Farklı programlama dillerini aynı çatı altında toplayan yazılım projelerinde belgelerin tek bir sitede sunulması teknik yazarlıkta önemli zorluklar barındırıyor. Her dilin kendine özgü API referans oluşturucusu bulunurken, projelerin ortak yazı tipi, tutarlı arama deneyimi ve uyumlu renk teması sunması gerekiyor. Teknik yazarlık alanında bu tür yapılar için henüz yerleşik bir kavram bulunmasa da süreç çok dilli dokümantasyon mimarisi olarak adlandırılıyor.
Söz konusu sorunun çözümünde dönüştürme ve doğrudan gömme olmak üzere iki temel yaklaşım öne çıkıyor. İlk yöntemde Doxygen veya benzeri araçların çıktıları Sphinx gibi ana sistemlerin anlayacağı biçime dönüştürülüyor. Ancak bu süreç derleme sürelerini uzatıyor, Doxygen ve rustdoc gibi araçların yerleşik arama yeteneklerini devreden çıkarıyor ve bağlantı hatalarına yol açıyor. Doğrudan gömme yaklaşımında ise her aracın çıktısı olduğu gibi yayımlanıyor fakat bu defa da sayfalar arası kopukluk ve parçalı gezinme sorunları ortaya çıkıyor.
pigweed.dev platformu Doxygen, rustdoc ve Sphinx çıktılarını bir araya getiren doğrudan gömme mimarisini tercih etti. Geliştiriciler, sayfalar arasındaki kopukluğu gidermek için tüm alt sitelere ortak bir başlık alanı ve statik arama motoru Pagefind entegrasyonu ekledi. Yapılan işlem sayesinde farklı araçlarla üretilen tüm sayfalar tek bir arama dizininde toplanarak gezinme deneyimi bütüncül hale getirildi.
Bu özet yapay zekâ ile hazırlanmıştır; ayrıntılar ve doğrulama için orijinal kaynağa başvurun.