Geliştiricilerin Gerçekten İzlediği API Dokümantasyon Videoları

Yazılı API referansı kesin, eksiksiz ve başlangıç noktası olarak neredeyse kullanışsızdır. Uç nokta listenize gelen bir geliştirici her alanın ne anlama geldiğini bilir; yine de API’nizle geçireceği ilk beş dakikanın nasıl göründüğü hakkında hiçbir fikri yoktur.

Kısa bir video tam da bu boşluğu doldurur. Referansın yerine değil, yanına geçer. Gerçek bir anahtar, gerçek bir istek ve gerçek bir yanıt gösteren üç dakika, dokümanın yanıtlayamadığı soruya cevap verir: bu gerçekten düşündüğüm gibi mi çalışıyor?

Bu videoları kalıcı biçimde faydalı olacak şekilde nasıl çekeceğinizi anlatalım.

Neyin Video Hak Ettiğine Karar Verin

Videonun bakımı pahalıdır. Metnin en zayıf olduğu yerde harcayın:

• İlk başarılı çağrı: Boş bir terminalden 200 yanıtına. Çekebileceğiniz tek en değerli video budur
• Kimlik doğrulama akışları: OAuth yönlendirmeleri, token değişimi ve yenileme mantığı birer sıralamadır. Video da tam olarak sıralamalar içindir
• Çok adımlı iş akışları: Kaynak oluştur, durumu sorgula, sonucu al. Referans bunları birbiriyle ilgisiz üç uç nokta gibi gösterir
• Webhook’lar ve geri çağrılar: İki sistemin birbiriyle konuşmasını düz yazıyla anlatmak gerçekten zordur
• Sık karşılaşılan hatalar: 401 alıp bunu düzelten bir video, konuyla ilgili herhangi bir paragraftan daha fazla destek talebini önler

Video hak etmeyenler: tek tek uç nokta parametreleri, enum değerleri, hız limiti sayıları. Bunlar aranabilen, kopyalanabilen ve saniyeler içinde güncellenebilen metinde durmalı.

Kayıt İçin Sandbox Hazırlayın

Asla gerçek bir anahtarla canlı ortama karşı kayıt almayın. Kayda başlamadan önce ayrı bir ortam kurun.

• Tek kullanımlık sandbox hesabı kullanın; anahtarları hemen sonrasında değiştirin
• Gerçekçi veri yükleyin: test_user_1 ve "foo" demoyu sahte gösterir. İnandırıcı isimler, tutarlar ve zaman damgaları API’ye güven duyurur
• Kısa ömürlü anahtar biçimi varsa onu seçin; böylece bir karede görünen token zararsız kalır
• Kabuk ortamınızı kontrol edin: env çıktısı ve komut geçmişi, herhangi bir kod parçacığından daha fazla kimlik bilgisi sızdırmıştır
• Önbellekleri ve bağımlılıkları önceden hazırlayın ki kurulum kaydetmeyin
• Bildirimleri kapatın — yayınlanmış bir videoda beliren Slack önizlemesi gerçek bir olaydır

Sandbox olsa bile her kareyi herkese açık kabul edin. Birileri mutlaka duraklatacak.

Doğru Yakalama Kurulumunu Seçin

API demoları genelde iki üç yüzey içerir: terminal, editör, Postman veya Insomnia gibi bir API istemcisi ve bazen panel için bir tarayıcı.

• Her yüzey için pencere yakalama kadrajı dar tutar ve masaüstü dağınıklığını gizler
• Uygulama değiştirmek zorundaysanız pencereleri önceden yan yana dizip ikisini kapsayan bir alan yakalayın. Kayıt sırasında alt-tab yapmak izleyiciyi şaşırtır
• Metin ağırlıklı içerik için 30fps yeter; düşük kare hızı bit hızını daha keskin karakterlere bırakır
• Doğal çözünürlükte kaydedin — bulanıklığın kaynağı sonradan büyütmedir
• Yazı boyutlarını 18–24pt’ye çıkarın. Monitörde abartılı görünen boyut videoda genellikle tam kıvamındadır

Her Klibi Aynı Şekilde Kurgulayın

Bir ekran kaydı yığınını dokümantasyona dönüştüren şey tutarlılıktır. İşe yarayan dört adımlı yapı:

1. Hedefi tek cümleyle söyleyin: “Bir müşteri oluşturup ondan ücret tahsil edeceğiz.”
2. Kimlik doğrulamayı gösterin: Tek bir başlık olsa bile gösterin. İzleyicinin anahtarın nereye gittiğini görmesi gerekir
3. İsteği canlı kurun: Yazın ya da yapıştırıp her alanı tek tek anlatın. Her parametrenin neden orada olduğunu söyleyin
4. Yanıtı sesli okuyun: JSON üzerinde durun. Sonraki adımda işe yarayacak alanı gösterin

Sonra sıradakini duyurarak bitirin: “Bu id tahsilat için kullanacağımız değer — o da bir sonraki videonun konusu.”

JSON ve Kodu Okunur Hale Getirin

Çoğu API videosunun çuvalladığı yer burasıdır. İstek başarılı olur, yanıt ekranı doldurur ve izleyici okunmaz bir süslü parantez duvarı görür.

• Her şeyi biçimlendirin: jq üzerinden geçirin veya istemcide biçimlendirmeyi açın
• Önemsizi katlayın: Çoğu API istemcisi bölümleri katlamaya izin verir. Kimsenin umursamadığı meta verileri kapatın
• Kritik alana yakınlaşın: Önemli iki satıra uygulanan bir zoom, her türlü anlatımdan değerlidir. Recorded’da zoom’u kayıttan sonra editörde ekleyebilirsiniz; böylece çekim sırasında yalnızca çağrıları doğru yapmaya odaklanırsınız
• Alan adını metin katmanıyla belirtin: subscription_status alanını gösteren bir etiket, söylemekten daha hızlı okunur
• Bekleme sürelerini kesin: Ağ gecikmesi, yoklama döngüleri ve yeniden derlemeler ölü zamandır. Kesin ve geçen süreyi kısa bir altyazıyla belirtin

Şartname Gibi Değil, Meslektaş Gibi Anlatın

Resmî açıklama zaten referans sayfasında var. Seslendirmeniz dokümanın söyleyemediğini söylemeli:

• “Herkesin unuttuğu başlık tam olarak bu.”
• “Evet, isteğe bağlı görünse de bu alan zorunlu.”
• “Burada 422 alıyorsanız neredeyse her zaman tarih biçimi yüzündendir.”

Bu tür yorumlar aslında bir doküman videosunun esas ürünüdür. Kayıttan önce üç dört tanesini yazın — doğru yazmaya odaklanınca kolayca unutulurlar.

Klipleri Kısa ve Modüler Tutun

Yirmi dakikalık “eksiksiz API turu”, tek bir uç nokta değiştiği anda ölür. Tek bir göreve odaklı iki-dört dakikalık klipler çok daha uzun yaşar ve tam olarak açıkladıkları referans bölümünün yanına gömülebilir.

Modüler olmak yeniden çekilebilir olmak demektir de. İstek gövdesi değiştiğinde uzun bir videoyu ameliyat etmek yerine doksan saniyelik tek bir klibi yeniden çekersiniz.

API’nin Değişeceğini Hesaba Katın

Video dokümantasyon, yazılı dokümantasyondan daha hızlı bayatlar. Bunu baştan planlayın:

• Sürüm numarasını hem söyleyin hem ekranda gösterin ki eskimiş bir video açıkça eskimiş görünsün
• Çabuk eskiyen arayüz öğelerinden kaçının — panel yeniden tasarımı bir videoyu API değişikliğinden hızlı yaşlandırır
• Yalnızca dışa aktarımları değil, ham kayıtları ve proje dosyalarını da saklayın; yeniden kurgu yeniden çekim anlamına gelmesin
• Dosyaları uç nokta ve sürüme göre adlandırın ki bir sürüm sonrası neyin güncelleneceğini hemen bulun
• Her ana sürümde klipleri gözden geçirin ve artık doğru olmayanları yeniden çekin

Geçen çeyrekten kalma kısa ve dürüst bir video sorun değildir. Artık var olmayan bir uç noktayı kendinden emin biçimde gösteren bir video ise güveninize mal olur.

Sorunun Sorulduğu Yerde Yayınlayın

En iyi konumlandırılmış API videosu, kimsenin uğramadığı ayrı bir video kitaplığında değil, doğrudan ilgili uç noktanın referans sayfasına gömülmüş olandır. İki dakikayı aşan videolara bölüm veya zaman damgaları ekleyin, videodaki kodun tamamını oynatıcının altına kopyalanabilir metin olarak koyun ve başarılı yanıtın kısa bir GIF’ini hızlı başlangıç sayfası için dışa aktarın.

Hızlı Kontrol Listesi

• Tek kullanımlık anahtarlı sandbox hesabı
• Gerçekçi örnek veri
• Bildirimler kapalı, kabuk geçmişi temiz
• Yazı boyutları büyütülmüş, pencereler yerleştirilmiş
• Hedef → kimlik doğrulama → istek → yanıt yapısı
• Biçimlendirilmiş JSON, kritik alanlarda zoom
• Bekleme süreleri kesilmiş
• Sürüm ekranda belirtilmiş
• İlgili referans bölümünün yanına gömülmüş
• Videonun yanında kopyalanabilir kod

Referans dokümanı geliştiriciye neyin mümkün olduğunu söyler. İyi bir kayıt ise bunun gerçekten çalıştığını gösterir — ve onu ilk başarılı çağrısına götüren genellikle budur.