Belgelendirme ve Stil Kılavuzu Entegrasyonu

Belgeleme olmadığında her geliştirici kuralları yeniden keşfeder: hangi başlık sırasının kullanılacağı, hangi sınıf adlarının mevcut olduğu, modal pencere yerine ne zaman çekmece kullanılacağı. Belgelenmiş bir stil kılavuzu doğru yanıtı bulunabilir hale getirir ve büyük ölçekte tahmin yürütme gereğini ortadan kaldırır.

Storybook, Histoire (Vue) ve Ladle gibi araçlar bileşenleri belgeleriyle birlikte yalıtılmış biçimde oluşturur; örnek her zaman gerçek kodla uyumludur. Statik belge dosyaları (bir vikide veya depoda bulunanlar) kaçınılmaz olarak güncelliğini yitirir; canlı belgeleme ise bunu yapmaz.

Her bileşen için onu kullanmak üzere gereken en kısa HTML'yi gösterin: <app-button variant="primary">Save</app-button>. Varyantları (birincil, ikincil, tehlike), durumları (yükleniyor, devre dışı) ve sınır durumlarını (uzun metin, simgeli, tam genişlik) gösterin. Gerçek bir sayfaya tam olarak kopyalanıp yapıştırılabilen örnekler, ekiplerin gerçekten kullandığı örneklerdir.

En iyi belgeler örneği kaynak kodun yanında oluşturur. Storybook bunu yerel olarak destekler; mdx-deck, Docusaurus ve Astro Starlight canlı JSX içeren MDX desteği sunar. İşaretlemeyi okurken gerçek sonucu görmek, “bu çalışıyor mu?” kuşkusunu doğrudan ortadan kaldırır.

Her bileşene yerleştirilmiş erişilebilirlik davranışını belgeleyin: hangi klavye etkileşimleri, hangi ARIA rolleri ve hangi odak yönetimi kullanılıyor. Bileşeni benimseyenler erişilebilirlik açıklamasını hazır olarak alır; inceleyenler de sözleşmeyi ihlal etmediklerini doğrulayabilir.

Açık anti-kalıpları gösterin: “Önemli, geçici geri bildirimler için modal pencere kullanmayın; bunun yerine bildirim kullanın.” Olumsuz bir örnek çoğu zaman olumlu bir örnekten daha akılda kalıcıdır. Başarısızlık biçimlerini görünür kılmak için her Yapılacak önerisini açık bir Yapılmayacak önerisiyle eşleştirin.

Adlandırma kalıplarını belgeleyin: BEM, atomik CSS, CSS Modules ve Tailwind yardımcı sınıf bileşimi. Sınıf adları, özel özellik adları ve dosya yolları için kuralları açıkça yazın. Tutarlı adlandırma zihinsel yükü azaltır; tutarsız adlandırma ise her geliştiricinin sonsuza dek zaman kaybetmesine neden olur.

Yalnızca kararların ne olduğunu değil, neden alındığını da kaydedin. “Vue yerine React'i seçtik, çünkü…” ifadesi gelecekte katkı sağlayacak kişiler için bağlamı korur. Kodun yanında Markdown biçiminde tutulan mimari karar kayıtları, ekip değişikliklerinden etkilenmeyen hafif bir biçimdir.

Yeni ekip üyeleri ilk bileşenlerini bir gün içinde kullanıma sunabilmelidir. Bir kontrol listesi şöyle olabilir: depoyu kurun, bağımlılıkları yükleyin, Storybook'u çalıştırın, doğru bileşen şablonunu bulun, belgeleri yazın ve bir PR açın. İlk PR'ye kadar geçen süreyi bir ölçüm olarak izleyin; daha kısa olması daha iyidir.

En iyi belgeler hem yeni arama yapanların hem de deneyimli kişilerin kolayca bulabileceği belgelerdir. Arama özellikli bir belge sitesi kullanın (Docusaurus için Algolia, Starlight için yerleşik arama). Bileşenleri birden çok eş adla etiketleyin; “Modal pencere” bileşeni Diyalog, Açılır Pencere veya Kaplama aramalarıyla da bulunabilsin.

Belgeleri görsel regresyonla eşleştirin: Chromatic her PR'de her Storybook hikâyesinin görüntüsünü alır ve görsel farkları gösterir. Belgeler genelinde Düğmenin stilini yanlışlıkla değiştiren birleştirilmiş PR kendisini engeller. Böylece belgeleme, tasarım sisteminin etkin testiyle birleştirilir.

Yalnızca bakım sorumlusunun bildiği şeyleri belgeleyin: dikkat edilmesi gereken noktaları, yarım kalmış soyutlamaları ve temizlenmeyi bekleyen geçici çözümleri. Gelecekteki siz veya yerinize geçecek kişi, bu kurumsal bilgiyi unutmadan önce kaydettiğiniz için size teşekkür edecektir.

Kodun yanında oluşturulan canlı belgeleme neden statik belge dosyalarına tercih edilir?

Belgeleme, tasarım sisteminin değerini katlayan etkendir. Gerçek bileşen kodunu içe aktaran canlı belgeleme araçlarını (Storybook, Histoire, Ladle) kullanın. Kullanılabilir en kısa örnekleri gösterin, erişilebilirliği belgeleyin, kararları kaydedin, Yapılacaklar/Yapılmayacaklar çiftleri yazın ve görsel regresyon testleriyle eşleştirin. Belgeleri sonradan düşünülen bir iş değil, birinci sınıf bir çıktı olarak ele alın.