Üreticinin yazamadığı kısmı yazmak
Üretilen doküman “bu uç ne alıyor” sorusunu cevaplar. Kimse o soruda takılmadı.
API Documentation koleksiyonlarınızdan üretiyor, üstüne zengin metin düzenleyici, sürüm yönetimi, kod parçacığı üretimi, PDF dışa aktarma ve paylaşılabilir bağlantı veriyor.
Üretilen yarı eksiksiz ve doğru; tek başına kimseye yardımı yok. Bir geliştiriciyi tıkayan şey hiçbir zaman parametre listesi olmadı.
Belgeyi ilk kez okuyana göre sıralayın
Uç listeleri genelde alfabetiktir; kimseye hizmet etmeyen sıra da odur. Belgeyi birinin entegre ettiği sırayla dizin:
- Kimlik doğrulaması, tam ve çalışan tek bir örnekle.
- Kurulumun çalıştığını kanıtlayan tek çağrı — bir şey döndüren en küçük istek.
- Ana akış, gerçekleştiği sırayla.
- Geri kalan her şey, alfabetik; çünkü o noktada okuyucu okumuyor, arıyordur.
Başarılı ilk çağrıya ulaşan okuyucu sabırlı olur. On dakikada kimlik doğrulayamayan okuyucu destek yazar ve sinirli kalır.
Başarıyı değil hataları belgeleyin
Üretilen her doküman 200’ü anlatır. Neredeyse hiçbiri e-postanın zaten kayıtlı olduğu anlamına gelen 409’u ya da istemcinin bu durumda ne yapması gerektiğini anlatmaz — tekrar dene, mesaj göster, başka bir çağrıya düş.
Hata tablosunu elle yazın. En çok okunan bölüm odur ve destek yazışmasını kısaltan tek bölüm de odur.
Sürüm ne zaman kesilir
Sürüm yönetimi, ekibinizin dışından biri API üzerine geliştirmeye başladığı gün yerini hak eder. Sürümü bir yayın kilometre taşında değil o anda kesin.
Sebep pratik: sonradan bir alanı değiştirdiğinizde geçen çeyrekte entegre eden kişinin ihtiyacı, alanın taşındığını anlatan bir değişiklik notu değil, belgenin o günkü hâlidir. Belirli bir sürüme bağlantı paylaşmak hiçbir şeye mal olmaz ve tartışmayı çıkmadan bitirir.
Dışarıdan okuyucusu olan her şeyde PDF yerine bağlantı paylaşın. Bağlantı sürümü izler; PDF gönderdiğinizin ertesi günü yanlış olmaya başlar.
Gerçekten sorulan sorular
Dokümantasyon hangi sırada olmalı?
Tam örnekli kimlik doğrulama, sonra kurulumun çalıştığını kanıtlayan en küçük çağrı, sonra ana akış sırasıyla, sonra geri kalanı alfabetik. En baştan alfabetik olmak ilk kez entegre eden hiç kimseye hizmet etmez.
Neyi elle yazmalıyım?
Hataları ve her ucun neden var olduğunu. Üretici parametreleri eksiksiz kapsıyor; kimse parametre listesinde tıkanmadı, herkes açıklanmamış bir 409’da tıkandı.
Yeni sürümü ne zaman kesmeliyim?
Ekibinizin dışından biri API üzerine geliştirmeye başladığı gün — yayın kilometre taşında değil. O kişinin ihtiyacı, entegre ettiği günkü belgedir; bir alanın taşındığını söyleyen not değil.
