DocC’de Temel Markdown’ın Ötesinde
Çoğu geliştirici DocC’nin standart markdown desteklediğini bilir, ama şaşırtıcı derecede az kullanılan iki güçlü direktif var: video gömme ve sekmeli içerik. Her ikisi de Xcode’un dokümantasyon görüntüleyicisinde ve barındırılan DocC web sitelerinde çalışıyor.
Video Gömme
Dokümantasyonuna video eklemek tek bir direktifle yapılıyor:
@Video(source: "setup-walkthrough.mp4")Video dosyasını dokümantasyon kataloğunun Resources klasörüne yerleştir. Bu, dokümantasyonun içinde doğrudan satır içi bir video oynatıcısı olarak render ediyor; harici bir URL’ye bağlantı vermekten veya görsel bir süreci metin olarak anlatmaktan çok daha etkili. Kurulum rehberleri, UI yürüyüşleri veya animasyon gösterimleri için iyi çalışıyor.
TabNavigator ile Sekmeli İçerik
Alternatif yaklaşımlar veya platforma özel talimatlar göstermen gerektiğinde, sekmeler okuyucuyu bunaltmadan şeyleri düzenli tutuyor:
@TabNavigator {
@Tab("SwiftUI") {
Use the `.environment` modifier to inject dependencies.
}
@Tab("UIKit") {
Override `viewDidLoad` and configure your dependencies there.
}
}Bu, okuyucuların bölümler arasında geçiş yapabildiği düzgün bir sekmeli arayüz olarak render ediyor. Birden fazla platformu, API sürümlerini veya yapılandırma yaklaşımlarını kapsayan dokümantasyon için özellikle yararlı.
Pratik Tavsiyeler
Contributing rehberimi bu iki özelliği de kullanacak şekilde güncelledim ve sonuç bir metin duvarından belirgin şekilde daha yaklaşılabilir oldu. Video, paragraflarla anlatılması gereken kurulum sürecini gösteriyor ve sekmeler platforma özel adımları temiz bir şekilde ayırıyor.
Bu direktifler Apple’ın DocC dokümantasyonunda belgelenmiş ama öğreticilerde nadiren bahsedilmiş. Açık kaynak bir Swift paketi sürdürüyorsan, bunları dokümantasyon kataloğuna eklemeyi düşün – insanların dokümanlarını nasıl deneyimlediğinde gerçek bir fark yaratıyorlar.