BELGELEME

BELGELEME
Ian Sommerville
Software Engineering Vol.2,
IEEE Press. Second Ed.
1
Giriş -1
2

Tüm yazılım projeleri için belgeleme gerçekleşir.

Bir proje için üretilen belgeler;
1. Geliştirme grubu arasında iletişim sağlamalı.
2. Yazılım bakımından sorumlu kişilere bilgi
sağlamalı.
3. Yönetimin, geliştirme sürecini planlaması,
maliyet ve zamanlama için bilgi sağlamalı.
4. Kullanıcıların sistemi kullanması ve yönetmesi
için bilgi sağlamalı.
Giriş -2


3
Bu dökümanları oluşturmak ağırlıklı olarak
yazılım mühendislerinin görevi.
Farklı doküman türleri, doküman kalitesinin
önemi, döküman yapısı, dökümantasyon
standardı, etkin yazım stili vb.
Süreç ve Ürün Dökümantasyonu -1


4
Tüm projeler için oluşturulacak tek bir
doküman listesi tanımlanamaz.
Yapılan anlaşmaya, geliştirilen sistem türüne,
beklenen yaşam süresine, geliştiren
kuruluşun kültürüne ve büyüklüğüne ve
geliştirme için yapılan zamanlamaya bağlıdır.
Süreç ve Ürün Dökümantasyonu -2
1.
2.
Süreç dökümantasyonu: Geliştirme ve
bakım sürecini belgelerler. Planlar,
zamanlamalar, ürün-kalite dökümanları,
kurumsal ve proje standartları.
Ürün dökümantasyonu: Geliştirilen ürünü
tarif eder.
–
–
5
Sistem dökümanları: Ürünü geliştiren ve bakımını
yapan mühendislerin bakış açısıyla.
Kullanıcı dökümanları: Kullanıcılara yönelik olarak.
Süreç Dökümantasyonu -1

Geliştirmenin yönetimi için sürecin görünür
olması çok önemli.
1.
2.
3.
6
Planlar, zamanlamalar: Yöneticiler tarafından
hazırlanır.
Raporlar: Geliştirme sürecinde kaynaklar nasıl
kullanılıyor?
Standartlar: Süreç nasıl gerçekleştirilecek?
Kurumsal, ulusal veya uluslar arası
standartlardan geliştirilebilir.
Süreç Dökümantasyonu -2
4.
5.
7
Çalışma belgeleri: Projedeki teknik iletişim
dökümanları. Fikirler, gerçekleştirim
stratejileri, problemler, tasarım kararlarının
açıklaması vb.
E-posta mesajları: Yöneticiler ve geliştirme
grubu arasındaki günlük iletişimin detayları.
Süreç Dökümantasyonu -3


8
Süreç dökümanları kısa sürede
güncelliklerini kaybederler ve sistem
tamamlandıktan sonra muhafaza
edilmelerine gerek yoktur.
Ancak yazılımın yeni gereksinimler
dolayısıyla gelişimi sırasında yararlı
olabilecek bazı dökümanlar olabilir.
Ürün Dökümantasyonu

Ürünü anlatır, uzun bir yaşam süresine sahip
olur ve ürünle birlikte değişmesi, gelişmesi
gerekir.
–
–
9
Kullanıcı dökümanları, ürünün nasıl
kullanılacağını anlatır.
Sistem dökümanları ise özellikle bakım
aşamasından sorumlu mühendislere yardımcı
olur.
Kullanıcı Dökümantasyonu -1

Kullanıcı dökümantasyonu farklı kullanıcı
gruplarını hedeflemeli:
1.
2.
10
Uç kullanıcılar
Sistem yöneticileri.
Kullanıcı Dökümantasyonu -2
1.
2.
11
Fonksiyonel Tanımlama: Sistem
gereksinimlerinin tanımlandığı ve sistemin
sunduğu hizmetleri kısaca anlatan
döküman.
Tanıtım Klavuzu: Sistemin uç kullanıcılar
tarafından nasıl kullanılacağını örneklerle
anlatan bir doküman.
Kullanıcı Dökümantasyonu -3
3.
4.
12
Kurulum Dökümanı: Sistem yöneticilerinin
sistemi belirli bir ortamda kurmalarına
yönelik açıklama içeren bir doküman.
Sistemi oluşturan dosyalar, gerekli minimum
donanım vb.
Başvuru Kitabı: Sistemdeki olanakların nasıl
kullanılacağı, hata mesajları, hatalı
durumları düzeltme gibi bilgiler içerir.
Kullanıcı Dökümantasyonu -4
5.

13
Sistem Yönetim Klavuzu: Özellikle bazı tür
sistemler için, örn: diğer sistemlerle
etkileşimde olan, gerekli bilgiler.
Bunlara ek olarak, “quick reference card”,
“on line help” vb. bulunabilir.
Sistem Dökümantasyonu -1



14
Gereksinimler belgesinden, tasarım,
gerçekleştirim, kabul testi planına kadar
sistemi anlatan tüm dökümanları içerir.
Kullanıcı dökümanları gibi yapılanmalı, genel
bilgi, ayrıntılı bilgi.
İçerik?
Sistem Dökümantasyonu -2


15
Sistem geliştikçe tüm dökümanların
güncellenmesi büyük önem taşımaktadır.
Dökümanlar arası bağımlılıklar ve ilişkilerin
tutulması yardımcı olabilir.
Sistem Dökümantasyonu -3


16
Küçük sistemlerde daha dar kapsamlı olabilir.
Ama yine de gereksinimler, mimari tasarım
ve program kaynak kodu olmalı.
Dökümantasyonun güncellenmesi önemli!
Doküman Kalitesi


Doküman kalitesi önemli.
Doküman kalitesini etkileyen faktörler:
1.
2.
3.
17
Dökümantasyon standartları
Doküman kalite güvence süreci
Yazım stili
Doküman Yapısı -1


18
Dökümanlardaki materyalin nasıl bölüm ve
alt bölümlere ayrıldığı, dökümanın
okunabilirliğini ve kullanılabilirliğini etkiler.
Bölümlerin olabildiğince bağımsız olması,
ayrı ayrı okunmalarını ve değişiklik
gerektiğinde yapılmasını kolaylaştırır.
Doküman Yapısı -2


19
Tablo -1 (sf176), IEEE’nin kullanıcı
dökümanları standartında tanımlanan
doküman yapısını ve olması gereken
bileşenlerin listesini veriyor.
Bu bilgi genel bir standardı gösteriyor, bir
kuruluşta rehber olarak kullanılabilir,
tablodaki tüm bileşenler yer almayabilir.
Doküman Yapısı -3




20
Kapak sayfası
Bölümler ve alt bölümler, içindekiler, sayfa
numaralama
Indeks
Teknik terimler ve kısaltmalar için sözlük
Dökümantasyon Standartları -1


21
Doküman standartları, doküman kalite
güvence için bir temel oluşturur ve tutarlı bir
görünüm, yapı ve kalite sağlarlar.
Dökümantasyon sürecinde kullanılabilecek
diğer standartlar, süreç, ürün ve değişim
standartları olmaktadır.
Doküman Standartları -2

Süreç standartları: Kaliteli doküman üretimi için
izlenmesi gereken standartlar.
–

Kullanılacak araçlar ve kaliteli doküman üretimini
sağlayacak kalite güvence süreçlerinin tanımlanmasıyla
ilgili standartlar.
Ürün Standartları: Dökümanla ilgili standartlar
–
–
Tüm dökümanların tutarlı bir görünümü ve yapısı olmalı.
Kurumsal standartlara bağlı.
1.
2.
3.
4.
22
Doküman tanımlama standartları
Döküman yapısı standartı
Doküman sunum standartları
Doküman güncelleme standartları
Doküman Standartları -3

Değişim Standartları: Dökümanların
elektronik kopyalarının uyumlu olması çin
standartlar.
–
–
23
PDF, Microsoft Word vb.
Stil, şablon standartları.
Yazım Stili


24
Standartlar yardımcı olur ama dökümanın
kalitesi, yazan kişinin açık, net olarak teknik
bilgiyi ifade yeteneğine bağlı.
Dökümanlar da teftiş edilmeli.
On-line Dökümantasyon



25
Basit metin dosyaları veya etkileşimli
hypertext tabanlı yardım sistemleri.
Erişim kolay, güncelleme sağlanabilir ve
doküman içinde arama yapmak kolay.
Yazılı dökümanlara destek olarak
kullanılmaları daha uygun.
Doküman Hazırlama
1.
2.
3.
Doküman oluşturma
Dökümanı iyileştirme
Doküman üretimi
–
26
Kelime işlemciler ve metin düzenleyiciler.