BELGELEME Ian Sommerville, “Software Documentation”, Software Engineering Vol.2, IEEE Press. Second Ed.

Giriş -1 Tüm yazılım projeleri için belgeleme gerçekleşir. Bir proje için üretilen belgeler; Geliştirme grubu arasında iletişim sağlamalı. Yazılım bakımından sorumlu kişilere bilgi sağlamalı. Yönetimin, geliştirme sürecini planlaması, maliyet ve zamanlama için bilgi sağlamalı. Kullanıcıların sistemi kullanması ve yönetmesi için bilgi sağlamalı.

Giriş -2 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 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 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. 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. 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 Ç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 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. 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: Uç kullanıcılar Sistem yöneticileri.

Kullanıcı Dökümantasyonu -2 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 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 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 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 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 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: Dökümantasyon standartları Doküman kalite güvence süreci Yazım stili

Doküman Yapısı -1 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 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 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 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ı. 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. PDF, Microsoft Word vb. Stil, şablon standartları.

Yazım Stili 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 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 Doküman oluşturma Dökümanı iyileştirme Doküman üretimi Kelime işlemciler ve metin düzenleyiciler.