01Sorun ve çözüm
Teknik dokümantasyon hizmetimizde belgeleri sistemin kendisinden çıkarırız: kodu ve veritabanını okur, sunucu yapılandırmasını inceler, sistemi bilen kişilerle görüşür ve gördüğümüzü doğrulayarak yazarız. Teslim edilen belgeler kimin ne için okuyacağına göre düzenlenir; yöneticinin genel resme, geliştiricinin kuruluma, operasyon ekibinin arıza anında yapılacaklara hızla ulaşabileceği bir yapı kurarız.
02Kimler için
Teknik dokümantasyon hizmeti kimlere yarar
Belge ihtiyacı çoğu zaman bir devir, bir denetim ya da ekibe yeni biri katılırken acil hâle gelir.
- Yazılımı geliştiren firmayla yollarını ayırmak üzere olan ve sistemi başka bir ekibe devredecek şirketler
- Kilit geliştiricisi ayrılmadan önce bildiklerini kayıt altına almak isteyen işletmeler
- Yatırımcı ya da satın alan tarafın teknik incelemesine hazırlanan girişimler
- API'sini iş ortaklarına, bayilere veya müşterilerine açan ve entegrasyon desteğine boğulan yazılım şirketleri
- İhale, iç denetim ya da bilgi güvenliği çalışması kapsamında sistem belgesi istenen kurumlar
03İhtiyaçlar
Belgesiz sistemlerde yaşanan tipik sorunlar
Eksik belge sessiz bir risktir; bir olay yaşanana kadar kimse fark etmez.
- 01
Kişiye bağlı bilgi
Yayın adımları, sunucu erişimleri ve bazı iş kuralları yalnızca bir kişinin hafızasındadır. O kişi izne çıktığında bile iş durabilir.
- 02
Uzayan uyum süreci
Yeni katılan geliştirici projeyi kendi bilgisayarında çalıştırmak için günlerce soru sorar. Ekibin geri kalanı da bu süreçte kendi işinden kopar.
- 03
Tekrar eden entegrasyon soruları
API'yi kullanan iş ortakları alan anlamlarını, hata kodlarını ve kimlik doğrulama adımlarını her seferinde e-postayla sorar. Destek yükü, belgenin yokluğunun bedelidir.
- 04
Arıza anında belirsizlik
Bir servis durduğunda nasıl yeniden başlatılacağı, günlüklerin nerede tutulduğu ve kime haber verileceği yazılı değilse müdahale tahminle yapılır.
04Özellikler
Teknik dokümantasyon kapsamında hazırladığımız belgeler
Her projede hepsi gerekmez; hangi belgelerin önce yazılacağını ihtiyaca göre birlikte seçeriz.
- 01
Mimari genel bakış
Sistemi oluşturan uygulamalar, veritabanları, dış servisler ve aralarındaki veri akışı C4 modeli gibi katmanlı diyagramlarla anlatılır. Bir yönetici ilk sayfada, bir geliştirici ayrıntı katmanında aradığını bulur.
- 02
API referansı
Uç noktalar, istek ve yanıt örnekleri, hata kodları ve yetkilendirme adımları OpenAPI tanımına dönüştürülür. Bu tanımdan etkileşimli bir belge sayfası ve istemci kodu üretilebilir.
- 03
Kurulum ve geliştirme rehberi
Projenin sıfır bir bilgisayarda çalıştırılması, test verisinin yüklenmesi ve testlerin koşulması adım adım yazılır ve yeni bir ortamda denenerek doğrulanır.
- 04
İşletim el kitabı
Yayın, geri alma, yedekten dönme, sertifika yenileme ve sık görülen arızalar için uygulanacak adımlar ayrı ayrı belgelenir. Arıza anında okunacak sayfalar kısa ve komut odaklı tutulur.
- 05
Veri sözlüğü ve karar kayıtları
Önemli tabloların ve alanların anlamı, kişisel veri içeren alanların işaretlenmesiyle birlikte yazılır. Geçmişte verilmiş mimari kararlar da gerekçeleriyle kısa karar kayıtlarına dönüştürülür.
05Entegrasyonlar
Belgelerin yaşayacağı araçlar
Belge, ekibin zaten açtığı yerde durmalı; aksi hâlde kısa sürede unutulur.
- 01
Kod deposu içinde
Markdown dosyaları kodla aynı depoda tutulur, MkDocs ya da Docusaurus gibi araçlarla okunabilir bir siteye dönüştürülür; kod değişikliğiyle birlikte gözden geçirilir.
- 02
Kurumsal bilgi tabanı
Confluence, Notion ya da SharePoint kullanıyorsanız belgeler sizin sayfa yapınıza ve yetki düzeninize göre yerleştirilir.
- 03
Diyagram araçları
Diyagramlar Mermaid ya da PlantUML gibi metin tabanlı araçlarla çizilir, böylece görsel dosyası kaybolsa bile kaynaktan yeniden üretilebilir.
- 04
API belge portalı
OpenAPI tanımı Swagger UI ya da Redoc gibi bir arayüzle yayınlanır; iş ortakları test ortamında istek deneyebilir.
06Süreç
Teknik dokümantasyon hizmeti nasıl ilerler?
Adım 01
Analiz
İş akışınızı, kullanıcılarınızı ve mevcut sistemlerinizi dinleriz; kapsamı, öncelikleri ve kabul ölçütlerini yazılı hâle getiririz.
Adım 02
Tasarım
Ekran akışlarını ve veri modelini çıkarırız. Arayüzü sizinle gözden geçirip onay almadan geliştirmeye geçmeyiz.
Adım 03
Geliştirme
Kısa döngülerle çalışırız; her döngü sonunda çalışan bir sürümü test ortamında görürsünüz.
Adım 04
Test
İşlevsel testler, entegrasyon testleri ve temel güvenlik kontrolleriyle hataları yayından önce yakalarız.
Adım 05
Yayın
Sunucu, alan adı, yedekleme ve izleme ayarlarını yaparak canlıya alırız; ekibinize kısa bir kullanım eğitimi veririz.
Adım 06
Bakım
İsterseniz bakım ve destek anlaşmasıyla güncellemeleri, izlemeyi ve yeni geliştirmeleri sürdürürüz.
07Teknoloji
Teknik dokümantasyonun güncel kalması için kurduğumuz düzen
Belgelerin en büyük sorunu yazılmamaları değil, yazıldıktan bir süre sonra yanlış hâle gelmeleridir. Bunu önlemek için belgeleri mümkün olduğunca koda yakın tutarız: API referansı koddaki tanımlardan üretilir, kurulum adımları otomatik bir betiğe bağlanır, diyagramlar metin olarak sürüm kontrolüne girer. Kod incelemesi şablonuna “belge güncellendi mi” sorusunu eklemeyi öneririz.
Devamını okuDaha az göster
Belgelere parola, API anahtarı ya da bağlantı dizesi yazılmaz. Gizli bilgilerin nerede saklandığı ve kimin erişebildiği anlatılır, değerlerin kendisi bir parola yöneticisinde ya da anahtar kasasında kalır. Kişisel veri işleyen alanlar veri sözlüğünde işaretlenir; bu, KVKK kapsamındaki envanter çalışmalarınıza teknik bir kaynak sağlar.
Belgeler, sistemi hiç görmemiş bir geliştiriciye okutulup verilen adımlarla projeyi ayağa kaldırabildiği doğrulanmadan teslim edilmiş sayılmaz.
08Çalışma modelleri
Bu hizmette çalışma modelleri
09Sık sorulan sorular
Teknik dokümantasyon hakkında sık sorulan sorular
Teknik dokümantasyon fiyatları nasıl belirlenir?
Sistemdeki uygulama ve servis sayısı, istenen belge türleri, API uç noktası sayısı, sistemi bilen kişilere ulaşılabilirlik ve belgelerin hangi dilde hazırlanacağı belirleyicidir. Kapsam belge listesiyle birlikte yazılı olarak tanımlanır.
Sistemi yazan kişi artık yoksa belge hazırlayabilir misiniz?
Evet. Kodu, veritabanı yapısını, sunucu yapılandırmasını ve günlükleri okuyarak sistemin nasıl çalıştığını çıkarırız. Belirsiz kalan noktaları raporda açıkça işaretler, tahmini bilgi olarak yazmayız.
Belgeler Türkçe mi İngilizce mi hazırlanıyor?
İhtiyacınıza göre ikisinden biri ya da her ikisi. Yurt dışındaki iş ortaklarına açılan API belgeleri genellikle İngilizce, iç işletim belgeleri Türkçe hazırlanır.
Son kullanıcılar için kullanım kılavuzu da yazıyor musunuz?
Bu hizmetin odağı geliştirici ve operasyon belgeleridir. Ekran görüntülü kullanıcı kılavuzu da kapsama eklenebilir; kapsam görüşmesinde ayrıca konuşuruz.
Teknik dokümantasyon firması olarak kaynak kodumuza nasıl erişiyorsunuz?
Depoya salt okunur erişim yeterlidir. Sunucu yapılandırması için de okuma yetkisi talep ederiz; hiçbir ortamda değişiklik yapmayız ve iş bitince erişimlerin kapatılmasını isteriz.
Belgeleri sonradan kendi ekibimiz güncelleyebilir mi?
Belgeler bunun için tasarlanır. Teslimde belge yapısını ve güncelleme düzenini ekibinize anlatırız; şablonlar sayesinde yeni bir servis eklendiğinde aynı biçimde belgelenebilir.
10İlgili hizmetler