Verimli ve doğru ürün dokümantasyonu; API geliştiricileri, ürün ekipleri ve teknik liderler için kritik öneme sahiptir. Ancak geleneksel dokümantasyon araçları çoğu zaman yavaş, parçalı veya gereksiz teknik bilgi gerektirir. Bu kılavuzda, Apidog ile ürün dokümantasyonunu nasıl daha uygulanabilir, izlenebilir ve ekipler arası işbirliğine uygun hale getirebileceğinizi adım adım ele alacağız.
Ürün Dokümantasyonu Neden Hala Önemli?
İyi tasarlanmış bir uygulamada bile kullanıcıların, geliştiricilerin ve ekip üyelerinin özellikleri, iş akışlarını ve uç durumları anlamak için net dokümantasyona ihtiyacı vardır.
Uygulama içine uzun açıklamalar gömmek arayüzü karmaşıklaştırır. Dokümantasyonu ihmal etmek ise kullanıcı hatalarını, destek taleplerini ve ekip içi bilgi kaybını artırır.
Geleneksel araçlarda sık karşılaşılan sorunlar:
- Koda bağımlı yazarlık: Docusaurus gibi çözümler teknik bilgi gerektirebilir. Bu da ürün ve operasyon ekiplerinin geliştiricilere bağımlı kalmasına neden olur.
- Sürüm kontrolü sorunları: Aynı doküman üzerinde yapılan değişiklikler çakışabilir, manuel birleştirme gerekebilir veya güncellemeler kaybolabilir.
- Karmaşık yayınlama süreci: Bazı araçlar yeterli inceleme kontrolü sunmazken, bazıları her değişiklik için geliştirici desteği gerektirir.
Apidog ekibi olarak biz de bu darboğazlarla karşılaşmadan önce Docusaurus kullanıyorduk. Bu sorunları çözmek için dokümantasyon oluşturma, inceleme ve yayınlama süreçlerini tek bir platformda birleştiren Apidog yaklaşımını benimsedik.
Sonucu görmek için Apidog Yardım Dokümantasyonunu inceleyebilirsiniz.
Ekip İşbirliği: Dokümantasyon İş Akışımız
Apidog'da dokümantasyon yalnızca geliştiricilerin sorumluluğunda değildir. Ürün yöneticileri içerik taslaklarını hazırlar, operasyon ekibi doğruluk ve yayın kalitesini kontrol eder.
Temel roller:
- Ürün yöneticileri: Yeni özelliklere göre doküman taslaklarını oluşturur ve günceller.
- Operasyon ekibi: Yayın öncesi inceleme, düzeltme ve doğruluk kontrolü yapar.
- Ana dal koruması: Canlı dokümanlarda doğrudan düzenleme yapılmaz; değişiklikler önce izole bir dalda hazırlanır.
Bu yaklaşım, dokümantasyonu kod akışına benzer şekilde yönetmenizi sağlar: taslak oluştur, incele, onayla, yayınla.
Apidog'da Ürün Dokümantasyonu Oluşturma: Adım Adım
1. İçeriği Sprint Dallarıyla Düzenleyin
Yeni bir geliştirme sprinti başladığında, operasyon ekibi Apidog'da o sprint için ayrı bir dokümantasyon dalı oluşturur.
Bu dal, canlı dokümanları etkilemeden yeni içerikleri hazırlamak için kullanılır.
Uygulanabilir iş akışı:
- Sprint için yeni bir dokümantasyon dalı oluşturun.
- Güncellenecek mevcut dokümanları bu dala alın.
- Yeni özellikler için taslak dokümanlar oluşturun.
- Tüm değişiklikleri canlı dokümanlardan izole şekilde hazırlayın.
- İnceleme tamamlandığında değişiklikleri ana dala birleştirin.
Bu yöntem şu avantajları sağlar:
- Canlı dokümanlar yanlışlıkla bozulmaz.
- Her sprintin dokümantasyon değişiklikleri izlenebilir olur.
- Yayın döngüsü ile dokümantasyon döngüsü senkronize ilerler.
Bu yaklaşımı “dokümanlar için branch tabanlı çalışma modeli” olarak düşünebilirsiniz.
2. Gelişmiş Markdown Düzenleyici ile Yazın
Apidog'un Markdown düzenleyicisi, hem teknik hem de teknik olmayan ekip üyelerinin hızlı dokümantasyon yazabilmesi için tasarlanmıştır.
Ürün yöneticileri standart Markdown sözdizimini kullanarak içerik hazırlayabilir. Aynı zamanda görsel düzenleme araçlarıyla daha zengin dokümanlar oluşturabilir.
Pratik kullanım örnekleri:
- Başlık ve alt başlıklarla özellik akışını yapılandırın.
- Kod bloklarıyla örnek istek veya yanıtları gösterin.
- Bilgi bloklarıyla önemli uyarıları öne çıkarın.
- Mermaid diyagramlarıyla süreç veya entegrasyon akışlarını görselleştirin.
- Tablolarla parametreleri, durumları veya seçenekleri karşılaştırın.
Örnek Markdown yapısı:
## Yeni Özellik: API Anahtarı Oluşturma
Kullanıcılar artık ayarlar ekranından yeni API anahtarı oluşturabilir.
### Adımlar
1. Ayarlar sayfasına gidin.
2. API Anahtarları sekmesini açın.
3. Yeni Anahtar Oluştur butonuna tıklayın.
4. Oluşturulan anahtarı güvenli bir yerde saklayın.
> Not: API anahtarı yalnızca oluşturulduğu anda görüntülenir.
Referans Bağlantıları
Apidog içinde dokümanları API uç noktalarına veya ilgili içeriklere bağlayabilirsiniz. Bu, okuyucunun bağlam değiştirmeden ilgili API referansına ulaşmasını sağlar.
Zengin İçerik Blokları
Dokümantasyona aşağıdaki öğeleri ekleyebilirsiniz:
- Simgeler
- Bilgi ve uyarı blokları
- Adım adım kılavuzlar
- Mermaid diyagramları
- Videolar
- Tablolar
Böylece ürün ve operasyon ekipleri, geliştirici desteği beklemeden kullanıcıların takip edebileceği net dokümanlar hazırlayabilir.
3. Gerçek Zamanlı İşbirliği ve İnceleme Yapın
Taslak hazırlandıktan sonra operasyon ekibi sprint dalını inceler.
İnceleme sırasında odaklanılması gerekenler:
- İçerik doğru mu?
- Adımlar kullanıcı tarafından uygulanabilir mi?
- Ekran görüntüleri güncel mi?
- İlgili API referansları veya bağlantılar eklenmiş mi?
- Metin, hedef kullanıcı için yeterince açık mı?
Apidog bu süreci şu özelliklerle destekler:
- Anlık düzenleme bildirimleri: Ekip üyeleri değişikliklerden gerçek zamanlı olarak haberdar olur.
- Yerleşik sürüm geçmişi: Değişiklikleri karşılaştırabilir, kabul edebilir veya geri alabilirsiniz.
- Tekrarlı inceleme döngüsü: Ürün ve operasyon ekipleri içerik yayınlanmaya hazır olana kadar aynı dal üzerinde birlikte çalışabilir.
Pratik kontrol listesi:
- [ ] Özellik adı doğru mu?
- [ ] Adımlar güncel ürün arayüzüyle eşleşiyor mu?
- [ ] Gerekli ekran görüntüleri eklendi mi?
- [ ] API bağlantıları doğru uç noktalara gidiyor mu?
- [ ] Uyarılar ve kısıtlamalar açık mı?
- [ ] Yayın öncesi son okuma yapıldı mı?
Bu yapı, uzun yorum zincirlerini ve manuel sürüm karşılaştırmalarını azaltır.
4. Test Edin ve Yayın Öncesi İnceleme Yapın
Dokümantasyonda doğruluk kritik öneme sahiptir. Yayına almadan önce dokümandaki her adımın gerçek ürün davranışıyla eşleştiğini kontrol edin.
Bizim uyguladığımız süreç:
- Yeni özellik üretim veya doğrulama ortamında test edilir.
- Adımlar tek tek uygulanır.
- Güncel ekran görüntüleri alınır.
- Ekran görüntüleri ilgili dokümana eklenir.
- Operasyon ekibi son doğruluk kontrolünü yapar.
Yayın öncesi kontrol akışı:
- Operasyon incelemesi: Sprint kapsamındaki tüm dokümanların doğru olduğu onaylanır.
- Birleştirme isteği gönderimi: Operasyon ekibi değişiklikleri ana dala göndermek için MR oluşturur.
- Yönetici onayı: Yetkili ekip üyeleri MR'ı inceler ve onaylar.
- Yayınlama: Birleştirilen dokümanlar kullanıcılar için yayına alınır.
Bu süreç, dokümantasyonun yalnızca yazılmış değil, doğrulanmış olmasını sağlar.
Apidog'un Dokümantasyon Sitelerini Optimize Etmesinin Diğer Yolları
1. Özel Markalama ve Düzen Kullanın
Dokümantasyon sitenizi şirketinizin marka kimliğiyle uyumlu hale getirebilirsiniz.
Yapılandırabileceğiniz öğeler:
- Logo
- Üst menü bağlantıları
- Şirket kaynakları
- Açık API dokümanlarına hızlı erişim
- Ürün tonuna uygun arayüz düzeni
Örnek yapı:
Üst Menü:
- Dokümantasyon
- API Referansı
- Yardım Merkezi
- Şirket Kaynakları
Bu yapı, kullanıcıların ürün dokümanları ile API referansları arasında daha hızlı geçiş yapmasına yardımcı olur.
2. Tek Tıklamayla, Sıfır Bakım Dağıtımı Yapın
Apidog'da yayınlama süreci, dokümanları yayına almak için ek altyapı yönetimi gerektirmez. Yayınlama işlemi tamamlandığında dokümanlar Apidog tarafından barındırılan alan adı üzerinden erişilebilir olur.
Daha fazla kontrol gerektiğinde şu ayarları yapılandırabilirsiniz:
- Özel alan adı
- Site araması
- Algolia entegrasyonu
- Google Analytics
- Yönlendirmeler
- Kaynak bağlantıları
Bu sayede operasyon ekibi, mühendislik desteği olmadan dokümantasyon sitesinin temel ayarlarını yönetebilir.
3. SEO İçin Hazır Bir Dokümantasyon Yapısı Kullanın
Dokümantasyon yalnızca mevcut kullanıcılar için değil, arama motorları üzerinden gelecek yeni kullanıcılar için de bulunabilir olmalıdır.
Apidog, dokümanların keşfedilebilirliğini artırmak için şu alanlarda yapılandırma imkanı sunar:
- Otomatik oluşturulan temiz URL slug'ları
- Doküman bazında başlık düzenleme
- Meta veri düzenleme
- Slug özelleştirme
Yayın öncesi SEO kontrol listesi:
- [ ] Başlık açık ve arama niyetine uygun mu?
- [ ] Slug kısa ve okunabilir mi?
- [ ] Meta açıklama dokümanın amacını anlatıyor mu?
- [ ] İç bağlantılar ilgili dokümanlara yönlendiriyor mu?
- [ ] API referanslarına bağlantılar eklendi mi?
Bu yapı, dokümanların paylaşılmasını, dizine eklenmesini ve kullanıcılar tarafından bulunmasını kolaylaştırır.
Sonuç
Apidog; içerik oluşturma, inceleme, sürüm yönetimi ve yayınlama adımlarını tek bir platformda birleştirerek dokümantasyon iş akışını daha hızlı ve güvenli hale getirir.
API odaklı ekipler için pratik yaklaşım şudur:
- Sprint için ayrı bir dokümantasyon dalı oluşturun.
- Ürün ekibinin taslakları hazırlamasını sağlayın.
- Operasyon ekibiyle doğruluk ve kullanılabilirlik incelemesi yapın.
- Gerçek ürün davranışıyla test edin.
- MR ve onay sürecinden sonra ana dala birleştirin.
- Dokümanları yayına alın.
Ürün kılavuzları, geliştirici dokümanları veya API referansları yönetiyorsanız, bu iş akışı mühendislik yükünü azaltırken güncel ve uygulanabilir dokümantasyon yayınlamanıza yardımcı olur.
Kendi dokümantasyon sürecinizi sadeleştirmek istiyorsanız Apidog'u deneyin ve ekibiniz için nasıl çalıştığını görün.
Top comments (0)