Dokümantasyon Bir Özelliktir

Dokümantasyon ürününüzden ayrı değildir. Ürünün bir parçasıdır.

Birçok geliştirici hatalı bir model izler:

  • Özelliği geliştirin.
  • Özelliği test edin.
  • Özelliği yayınlayın.
  • Özelliği dokümante edin.

Kullanıcılar kodunuzu deneyimlemezler. Arayüzünüzü, iş akışlarınızı ve dokümantasyonunuzu deneyimlerler. Bir kullanıcı için dokümantasyon bir özelliktir.

Üreticiler dokümantasyonu ihmal ederler çünkü ürünü zaten anlıyorlardır. Belirli kararları neden aldığınızı bilirsiniz. API'nin nasıl çalıştığını bilirsiniz. Kısayolları bilirsiniz.

Kullanıcı bilmez. Size bariz gelen şeyler onlara gizemli gelir.

Tekrarlanan soruları dokümantasyon borcu olarak görün. Eğer insanlar aynı soruyu iki kez soruyorsa, bir sorununuz var demektir. Ya ürününüz kafa karıştırıcıdır ya da dokümanlarınız eksiktir. Bazen API'yi düzeltmeniz gerekir. Çoğu zaman ise dokümanları düzeltmeniz gerekir.

İyi dokümantasyon sürtünmeyi azaltır. Şu soruları hızlıca yanıtlar:

  • Bu nedir?
  • Neden bunu kullanmalıyım?
  • Nasıl başlarım?
  • En iyi yaklaşım nedir?
  • Basit bir örnek nedir?

Hedef eksiksizlik değil, ivme kazanmaktır.

Harika dokümantasyon, kalıpları ve niyeti öğretir. Bir framework'ün neden belirli bir şekilde çalıştığını açıklar. Bu, kullanıcıları daha etkili kılar.

Dokümantasyon işinizi sessiz yollarla etkiler:

  • Benimsenme oranları.
  • Onboarding hızı.
  • Destek maliyetleri.
  • Topluluk büyümesi.
  • Geliştirici deneyimi.

İyi dokümanların etkisini kolayca göremezsiniz. Kötü dokümanların eksikliğini ise anında fark edersiniz.

Dokümantasyonun aynı zamanda kendiniz için olduğunu unutmayın. Bilginizi gelecekteki kendiniz için korur. Kararları kaydeder, böylece aylar sonra cevapları yeniden keşfetmek zorunda kalmazsınız.

Ürün kalitesi ve dokümantasyon kalitesi birbirine bağlıdır.

  • Kafa karıştırıcı yazılımın daha fazla dokümantasyona ihtiyacı vardır.
  • Net yazılımın daha azına ihtiyacı vardır.
  • İyi dokümantasyon kötü tasarımı açığa çıkarır.

Dokümantasyonu sonradan akla gelen bir şey olarak görmeyi bırakın. Netliği sağlamak için kullanın. Netlik tasarımınızı iyileştirir. İyileştirilmiş tasarım ürününüzü iyileştirir.

Kaynak: https://dev.to/stinklewinks/documentation-is-a-feature-228n