Ürün Dokümantasyonu
Denomas ürün dokümantasyonu süreci — doküman türleri, docs-as-code, versiyon yönetimi ve çeviri
2 minute read
Ürün Dokümantasyonu
Bu sayfa, Denomas ürünlerinin dokümantasyon türlerini, docs-as-code yaklaşımını, versiyon yönetimini ve çeviri sürecini tanımlar.
Doküman Türleri
| Tür | Hedef Kitle | İçerik | Güncelleme Sıklığı |
|---|---|---|---|
| API Referansı | Geliştirici | Endpoint tanımları, parametre açıklamaları, örnek istekler/yanıtlar | Her sürümde |
| Kullanım Rehberi | Son kullanıcı | Adım adım görev tamamlama yönergeleri | Özellik değişikliğinde |
| Hızlı Başlangıç | Yeni kullanıcı | İlk kurulum ve temel kullanım (15 dakika hedefi) | Büyük sürümlerde |
| Mimari Dokümanı | Mühendis, mimar | Sistem mimarisi, veri akışı, bileşen ilişkileri | Çeyreklik |
| Sürüm Notları | Tüm kullanıcılar | Yeni özellikler, düzeltmeler, kırılma değişiklikleri | Her sürümde |
| Sorun Giderme | Destek, son kullanıcı | Bilinen sorunlar ve çözümleri | Sürekli |
Doküman Sorumluluğu
API referansı ve mimari doküman: @muhendislik-ekibi. Kullanım rehberi ve hızlı başlangıç: @urun-ekibi. Sürüm notları: ortak sorumluluk.
Docs-as-Code Yaklaşımı
Dokümantasyon, kaynak kod ile aynı süreçlerle yönetilir:
| Prensip | Uygulama |
|---|---|
| Versiyon kontrolü | Tüm dokümanlar Git deposunda tutulur. |
| İnceleme süreci | Doküman değişiklikleri merge request ile incelenir. |
| Otomatik derleme | CI/CD pipeline doküman sitesini otomatik oluşturur. |
| Markdown formatı | Tüm dokümanlar Markdown formatında yazılır. |
| Linting | Yazım ve biçim kuralları otomatik kontrol edilir (markdownlint). |
Doküman Deposu Yapısı
docs/
├── api/ # API referans dokümanları
├── guides/ # Kullanım rehberleri
├── quickstart/ # Hızlı başlangıç dokümanları
├── architecture/ # Mimari dokümanlar
├── release-notes/ # Sürüm notları
├── troubleshooting/ # Sorun giderme
└── translations/ # Çeviri dosyaları
├── en/
└── tr/
Versiyon Yönetimi
Dokümanlar, ürün sürümleriyle senkronize tutulur:
| Kural | Açıklama |
|---|---|
| Sürüm eşleştirme | Her ürün sürümü için karşılık gelen doküman sürümü bulunur. |
| Geriye dönük erişim | Önceki sürüm dokümanlarına erişim açık kalır. |
| Varsayılan sürüm | Doküman sitesi varsayılan olarak en son kararlı sürümü gösterir. |
| Kırılma değişikliği | API kırılma değişiklikleri sürüm notlarında ve migration rehberinde belgelenir. |
Doküman Güncelleme Süreci
- Geliştirici, kod değişikliğiyle birlikte doküman güncellemesini hazırlar.
- Teknik yazar içeriği düzenler ve tutarlılığı kontrol eder.
- Merge request ile inceleme yapılır.
- CI/CD doküman sitesini otomatik günceller.
Doküman Borcu
Dokümantasyonsuz özellik canlıya alınmaz. Sprint kapanışında doküman borcu kontrol edilir.
Çeviri Süreci
Denomas dokümanları birincil olarak Türkçe yazılır; gerekli durumlarda İngilizce çeviri eklenir:
| Adım | Sorumlu | Araç |
|---|---|---|
| Kaynak dilde yazım | Teknik yazar / geliştirici | Markdown editör |
| Çeviri | Çevirmen veya AI destekli çeviri | CAT araçları |
| Teknik inceleme | İlgili dildeki teknik incelemeci | Merge request |
| Terminoloji tutarlılığı | Sözlük (glossary) referansı | Glossary dosyası |
Çeviri Kuralları
| Kural | Açıklama |
|---|---|
| Teknik terimler | Yerleşik İngilizce teknik terimler çevrilmez (API, dashboard, pipeline vb.). |
| Glossary önceliği | Tüm çevirilerde glossary referans alınır. |
| Bağlam koruma | Çeviri, kaynak metnin teknik doğruluğunu korur. |
| Senkronizasyon | Kaynak metin güncellendiğinde çeviri de güncellenir (stale çeviri kabul edilmez). |
İlgili Sayfalar
- Ürün Yönetimi Süreci
- Teknik Yazar İş Ailesi
- Mühendislik
- Mühendislik
Geribildirim
Bu sayfa yararlı oldu mu?
Bu sayfa faydali oldu
Bu sayfa gelistirilmeli
