SODA Software Documantation Automation Yazılım Belgeleme Otomasyonu Hazırlayan: Tuba Kızık Hacettepe Üniversitesi Bilgisayar Mühendisligi Bölümü 20221743 15.01.2006
İçindekiler: 1. 1.1. Soda Nedir? 1.2. Bilgilerin Düzeltilmesi 1.3. Dinamik Domainler 1.4. Belge Yaratma 1.5. Şablon Düzenleme 1.6. Soda ve Microsoft Word 1.7. Soda nin Diğer Rational Ürünleriyle Entegrasyonu 2. Bileşenlerin Kurulumu 2.1. Gereksinimler 2.2. Temel Bileşenlerin Yüklenmesi ve Sistemle Entegrasyonu 3. Örneklerle Doküman Hazırlama Süreci 3.1. Basit Bir Rapor Yaratmak 3.2. Belgenin Bakımı 3.3. Yeni Alan Yaratma 3.4. Özel Şablon Yaratma 4. Kaynaklar
1. 1.1. SoDA Nedir? SoDa, Yazılım Belgeleme Otomasyonu anlamına gelen Software Documantation Automation kelimelerinin baş harflerinden meydana gelmiş bir kısaltmadır. Soda rapor ve çeşitli dokümanları hazırlamak için kullanımı kolay bir arayüz sunarken günlük raporların resmi bir yapıda, gereğine uygun olarak hazırlanmasını sağlar. Gereksinimler, tasarım, test ve hata durumlarını tek bir arayüz kullanarak raporlanmasına yardımcı olur. Soda, yazılım dokümantasyonunu otomatikleştirdiği için, belgeleme için gereken süreyi ve iş gücünü oldukça azaltır. Asıl gücü; yazılım üzerinde değişik kaynaklardan bilgi toplaması ve bu bilgileri kullanarak belirlenen bir şablona uygun bir biçimde rapor üretmesinden gelir. Yaratılmak istenen dokumanda kullanılmak üzere Soda bünyesinde birçok şablon bulunur, bu şablonlara ek olarak şablonüretme bileşenleri kullanılarak özelleşmiş gereksinimlere uygun olarak yeni şablonlar üretilebilir. Soda for Word: Microsoft Word kapsamına doküman yaratma özelliği ekler. Doküman yenileme sürecininde harcanan zamanı git gide azaltır. Doküman yenilendikçe eklenen verileri direk olarak dokümana ekler. Rational Rose, Rational RequisitePro gibi birçok farkılı bilgi kaynağı kullanarak veri birleştirmeye olanak sağlar. Dokümanlar ve bilgi kaynakları arasındaki tutarlılığın korunmasını sağlar. 1.2. Bilgilerin Düzeltilmesi: Bir Soda dökümanı yaratıldığında, bu dökümana hangi veri kümesinin kaynaklık edeceği belirlenmelidir. Soda veri kümelerini, tanım alanı manasında olan ve domain adı verilen özel program parçaları kullanarak derler. Her domain, Rational Rose ve File System gibi tek bir tür kaynak bilgi için kullanılır. Her domainin içinde bilginin belirli kaynak tarafından nasıl modelleneceği sınıflar, nitelikler ve bağıntılar türünde gömülü olarak bulunur. Örneğin, Rose domain ; bir sınıf kategorisinin isim ve dokümantasyon niteliklerinin bulunduğunu, bu sınıf kategorisinin sınıflara bağıntılar içerdiğini ve diğer paketlere bağıntılar gönderdiğini belirler. Bu tür özelleşmiş domain bilgisi tam anlamıyla istenen türde bir doküman elde edilmesini sağlar. Soda nın diğer bir yararı da, birçok domaini bir doküman içerisinde destekleyebilmesidir. Bu sayede bir proje hazırlanırken proje ekibi tasarım, kodlama ve de test için farklı özelleşmiş araçları kullanma ihtiyacı duymak ve kullanmayı öğrenmek yerine sadece bir tek belgeleme aracı kullanarak tüm bu ihtiyaçlarını bir elden halledebilir. 1.3. Dinamik Domainler ClearQuest ve RequisitePro gibi bazı domainler dinamik domainlerdir. Bu tür domainler çok az sayıda varsayılan türde nesne içerirler. Bu türdeki ürünler geliştirilirken bazı özel dinamik nesneler; örneğin
ClearQuest için özelleşmiş veri tabanı nesneleri, RequisitePro için ise proje içi özelleşmiş nesneler eklenir. Şablonlar tasarlanırken bu türde yaratılan nesneler raporlama için kullanışlı olacaktır. 1.4. Belge Yaratma Piyasada doküman üreten birçok ürün bulmak mümkündür Soda yı farklı kılan bir dokümanı tekrar nasıl yarattığıdır. Soda dokümanlar ve kaynaklar arasınaki tutarlılığı Akıllı Belge Birleştirme (Intelligent Document Merging) adı verilen bir süreç ile sağlar. Örneğin; Rose daki bir sınıf gibi, kaynak domainden bir nesne silindiğinde, Soda belge içindeki o nesneden üretilmiş olan kısımları siler. Ya da tam tersi olarak, kaynağa bir nesne eklendiğinde, Soda belgenin belirli bir kısmına yeni bir bölüm ekler. Akıllı Belge Birleştirme sürecinin tek avantajı tutarlılık değildir. Diğer bir avantajı, kaynak dışından derlenemeyen bilgileri ele alabilmesidir. Soda belge içine, denklemler, çizimler gibi özel biçimlemeler içeren tanımlayıcı metinlerin eklenmesine olanak verir. Belge tekrar yaratıldığında, kullanıcı tarafından yapılan eklemelerden etkilenmeden ve onları etkilemeden domainden alınan bilgileri günler. Soda nın diğer bir anahtar özelliği de belgenin sadece bir bölümünün tekrar yaratılabilmesidir. Örneğin kaynakta yapılan bir değişikliğin belgede sadece bir paragrafı değiştireceği biliniyorsa, sadece bu paragrafın tekrar üretilmesi istenebilir. Bu tür bir yeniden yaratma işlemi bütün belgeyi her seferinde tekrar yaratmaya göre oldukça hızlıdır. Ayrıca Soda bütün bu özelliklerine ek olarak, yaratılacak belgeyi Word ya da HTML dokümanı olarak yaratılabilmesini sağlar. 1.5. Şablon Düzenleme Soda bünyesinde tanımlı birçok şablon barındırır. Bu şablonlar aynen kullanılabildikleri gibi, kullanıcının özelleşmiş ihtiyaçlarını karşılamak adına şablon üzerinde ekleme silme ve değiştirme gibi çeşitli değişiklikler yapılarak da kullanılabilir. Ayrıca tamamen yeni şablonalar da üretilebilir. Soda şablonları Microsoft Word belgeleri olarak hazırlanırlar (.doc dosyaları). Bu yüzden Soda şablonları birçok kullanıcıya yabancı olmayan bir ortamda yaratılır ve düzenlenir. Şablon yaratma ve biçimlendirme işlemleri tamamen kullanıcıyla etkileşimli olarak gerçekleştirilir. Şablon hazırlamak için programcı olmaya yada bir programlama dili bilmeye gerek yoktur. Soda komutlarını özelleştirmek için diyalog kutuları kullanılır. 1.6. Soda ve Microsoft Word Soda şablonlarıyla Micosoft Word şablonları birbirlerine karıştırılmamalıdırlar. Soda şablonları.doc uzantılı, Micosoft Word şablonları ise.dot uzantılı olmakla beraber farklı kullanım alanları vardır: Soda şablonları domainden ne çıkarılacağını ve bu çıkarılan bilginin nasıl düzenleneceğini belirleyen.doc uzantılı Micosoft Word belgeleridir..doc uzantılı olan her Micosoft Word belgesi, belgenin biçimi ve belgedeki makrolar gibi elemanları saklayan.dot uzantılı bir Word şablonu ile ilişkilendirilmişlerdir. Sonuç olarak Soda şablonları bir Word şablonu ile ilişkilendirilmiş bir Word belgesidir.
1.7. Soda nın Diğer Rational Ürünleriyle Entegrasyonu: Soda birçok Rational aracı kullanarak yaratılacak belgeler için bilgi toplanmasına olanak sağlar. Soda aşağıdaki ürünlerin içinden çağrılma ve kullanılma imkanı vermektedir: : ClearQuest : ClearQuest veritabanındaki bağlantılar, geçmiş gibi öğelerden Soda için bilgi edinilebilir. : RequisitePro : RequisitePro veritabanındaki niteliklerden, gereksinimlerden ve projelerden Soda için bilgi edinilebilir. : Rose : Soda, belgelemelerde Rational Rose daki modeller ile bütünleşebilir. Böylece Soda, Rose daki kullanıcı senaryolarından, çizeneklerden ve paketlerden bilgi elde edebilir. : TestManager : Soda TestManager projelerinden, ve betiklerinden bilgi elde edebilir. : Rational Administrator : Soda, Rational Administrator programının kendisinden bilgi elde edebilir. Soda, aşağıdaki Rational araçlarından bilgi toplayabilir, ancak onların içinden çalışma imkanı vermez: : Apex NT : Ada üniteleri, biçemler, görününler(views) Soda belgelerindeki alt sistemlerle bütünleşebilirler. : ClearCase : ClearCase den sürüm kontrol, activite yönetimi, çalışma alanı(workspace) yönetimi ve VOB meta-data bilgisi elde edilebilir. : Rose RealTime : Soda, belgelemelerde Rational Rose RealTime daki modeller ile bütünleşebilir. Böylece Soda, Rose daki kullanıcı senaryolarından, çizeneklerden, paketlerden, sınıflardan, elemanlardan bilgi elde edebilir. : Rational XDE : Soda, belgelemelerde Rational XDE modelleri ile bütünleşebilir. Böylece Soda, paketlerden, sınıflardan, kullanıcı senaryolarından ve çizeneklerden bilgi toplayabilir.
Ayrıca Soda, şu alanlardan da bilgi toplamak amacıyla kullanılabilir: : Microsoft Project : Microsoft Project planından görev ve kaynak bilgileri elde edilebilir. : Microsoft Word : Biçimlendirilmiş ya da biçimlendirilmemiş (formatted/unformatted) olarak kullanılmak üzere Word belgelerinin içerikleri Soda tarafından belgeleme amaçlı kullanılabilir. : Dosya Sistemi : Kullanıcı kendi dosyalarındaki bilgileri Soda da belgeleme amaçlı kullanabilir. Bu bilgiler, kütüklerden, dosyalardan ya da kütük içindeki kayıtlardan oluşabilir. 2. Bileşenlerin Kurulumu 2.1. Gereksinimler: İşletim Sistemi Windows 2000, Windows NT ya da Windows XP olmalıdır. Ayrıca sistemde Microsoft Word programının yüklü bulunması gerekmektedir. 2.2. Temel Bileşenlerin Yüklenmesi ve Sistemle Entegrasyonu: Rational Soda for Word programı bir setup dosyası ve lisans anahtarını barındıran.upd uzantılı bir başka dosya ile birlikte internet üzerinden indirilebilir. Program kurulduktan sonra ilk çalıştırıldığında otomatik olarak Key Administration Wizard (Anahtar Yönetim Sihirbazı ) programı da açılır ve programı çalıştırmak için gereken anahtarın girilmesini ister. Burada sihirbazın, programın aktifleştirilmesi için.upd uzantılı olan anahtar dosyasına yönlendirilmesi gerekmektedir. Böylece program aktifleştirilmiş ve kullanıma hazır duruma gelmiş olur. 3. Örneklerle Doküman Hazırlama Süreci 3.1. Basit Bir Rapor Yaratmak Rapor yaratma temelde 3 aşamadan meydana gelir. Bunlar: - Bir şablon seçme - Bir veri kaynağı tanımlama - Raporu yaratma
Örnek olarak Rose bünyesindeki bir sample.mdl model dosyasını harici kaynak olarak kabul eden, ve bu dosyaya bağlı bir belge yaratacağız. sample.mdl dosyasının içerdiği ilişkilerin sınıf şeması aşağıdaki gibidir: Company Jobs workers Job Employee Person Şablon şeçme: 1. Program menüsünden Rational SoDA for Word seçilerek SoDA çalıştırılır. Bu komutla Soda menusu içeren bir boş bir Word dokümanı açılır. 2. Soda menusunden Getting Started başlığı seçilir. 3. Şablon seçme sihirbazının ikinci aşamasında, seçime sunulan şablonlar arasından isteğe en uygun olan şablon seçilir. Örneğimizde Rose\Classes.doc şablonunu seçelim.
4. Bir sonraki aşamada doküman istenen bir adrese kaydedilir. Belge, kaynak veri ile aynı adrese kaydedilmesi kolaylık sağlayacaktır. Bu örneğimizde Rational Rose içindeki sample.mdl model yapısını kaynak veri olarak kullanacağımızdan..\rational\sodaword\tutorial\ adresine kaydetmemiz uygun olacaktır. Bu adrese classes.doc adıyla kaydettiğimizi varsayalım. 5. Sihirbazın son aşamasında karşılaşılan pencerede Generate (oluştur) düğmesine basılmalıdır.
6. Böylece kaynak verinin tanımlanmasını isteyecek bir pencere ile karşılaşılacaktır. Örneğimizde harici kaynak olarak bir rose modeli kullandığımızdan, Identify the Rose Model penceresi açılacaktır. Burada Browse (gözat) butonu tıklanarak kullanılacak olan Rose modeli seçilebilir. örneğimizde rose bünyesinde örnek bir model dosyası olan simple.mdl dosyası seçilebilir.
7. OK (tamam) butonu tıklanarak belge yaratma işlemi başlatılır. Bu sırada performansı arttırmak için Word dokümanı minimize edilmiş (küçültülmüş) duruma otomatik olarak getirilir. 8. Belge yaratma işlemi bittikten sonra, ClassesRpt.doc adıyla yaratılmıs belge Word kullanılarak açılır. Burada dikkat çekilmesi gereken birkaç nolta vardır. İlki, yaratılan belge ayrı bir Word dokümanı şeklinde otomatik olarak kaydedilmiştir. Yaratılan belgedeki dört sınıfın her biri için bir bölüm ayrılmıştır. 3.2. Belgenin Bakımı Bu bölümde bir belge yaratılacak, şablon ve kaynakta değişiklikler yapılacak ve tüm belge tekrar yaratılacaktır. 1. Önceki bölümde yarattığımız classes.doc dokümanı seçilerek açılır. 2. Menudeki Soda bölümündeki Generate Document seçilir. 3. Soda Generator diyalog kutusu onaylandıktan sonra Soda belgeyi yaratmaya başlar. Performansın arttırılması için Word minimize edilmiş durumdadır. 4. Microsoft Word araç çubuğundaki Show/Hide ( ) sekmesi tıklandığında pembe ve sarı açıklama notları ile birlikte aşağıdaki gibi bir görünüm sağlanır.
5. Bu görünümde, bir sınıfın açıklamasının bittiği bir alana, [endlink] alanından sonra, istenilen bir açıklama girilip kaydedilebilir. Bu açıklama belge tekrar yaratıldığında belgeye eklenecektir. 6. Belge yine bu görünümdeyken, imleci bir sınıf açıklamasındaki mavi alanın üstüne getirip araç çubuğundaki Soda sekmesindeki Visit Source alanı tıklanır. 7. Bu durumda Rational Rose açılır. Word belgesindeki imlecin belirttiği sınıfın sınıf belirtim penceresi açılmıs durumdadır. Buradaki Documentation bölümündeki metin alanına istenilen açıklama yazılır ve tamam (OK) butonuna tıklanır. 8. Daha sonra Microsoft Word belgesindeki Soda menusundeki Generate Document sekmesi tıklanarak belge yeniden yaratma işlemi başlatılır. 9. Yeniden yaratılan belgede seçilen sınıfın tanım bölümünün değişmiş olduğu görülür. 3.3. Yeni Alan Yaratma Bu bölümde bir sınıf için belirlenmiş işlemlere göre, belgede yeni bir alan yaratılacaktır. 1. Daha önce hazırlanmış olan classes.doc belgesi Microsoft Word kullanılarak açılır. Pembe ve sarı açıklama cümleleri görünür durumda değilse araç çubuğundaki Show/Hide ( ) sekmasi tıklanarak açılır.
2. File menusundeki Save As sekmesi kullanılarak belge aynı klasor içine classesops.doc adıyla kaydedilir. 3. İmleç, istenilen bir sınıf için [ENDDISP] ile [ENDREP] açıklama cümlecikleri arasına getirilir ve iki yeni satır eklenir. 4. Soda menusundeki Template View sekmesi tıklanır. Template View (Şablon Görünümü) aşağıdaki gibidir: 5. Burada Select Class Values (sınıf değeri seç) listesinden MyOperations alanı seçilir. 6. Kullanılabilir değerler listesinden Name ve C++ Image değerleri seçilir ve Template View (Şablon Görününmü) penceresi kapatılır. 7. İmleç, classesops.doc şablonunda Operation Name (İşlem İsmi) alanına getirilir ve Word araç çubuğundaki sitiller fonksiyonu kullanılarak sitil Heading 3 yapılır. 8. Soda menusundeki Genarate Report sekmesi tıklanarak rapor üretilir. Oluşan raporun işlem isimlerini de içerdiği görülür. Bu rapor aşağıdaki gibi oluşacaktır:
3.4. Özel Şablon Yaratma Bu bölümde bir şablon görünümü (Template View) kullanarak yeni ve boş bir şablon yaratılacak, daha sonra Soda komutları eklenecek ve üzerinde değişiklikler yapılacaktır. 1. Microsoft Word üzerinde yeni bir sayfa açıklır. 2. Burada Soda Create Template.wiz (Soda Şablon Yarat) sekmesi çift tıklandığında bir şablon görünümü ( Template View ) ile beraber boş bir Soda şablonu açılır. 3. Şablon görünümünün sağ tarafında bulunan Rose Model seçilir. Böylece The Identify Model dayalog kutusu açılır. 4. Burada gözat (browse) butonu tıklanarak Soda\tutorial klasörü işaret edilir. Burada simple.mdl dosyası baz alınacağından bu model seçilir ve açılır. 5. Şablon görünümünün sağ tarafındaki AllPackages (Bütün paketler) sekmasi tıklanır. Rational Rose içinde kullandığımız Simple modeli sadece Logical View (Mantıksal Görünüm) içerdiğinden, burada kullanacağımız REPEAT komutu sadece mantıksal görünümden erişilebilir. 6. Şablon görünümünün sol tarafındaki REPEAT komutu değiştirilmesi için çift tıklanır. REPEAT komutu diyalog kutusu açılır. Bu diyalog kutusu aşağıdaki gibidir:
7. Advanced (Gelişmiş) kutusu seçilir. 8. Self nesnesinin içeriği açılarak Name sekmesine tıklanır. 9. Sağ işleç tıklanır ve Literal tıklanır. Tür Logical View ( Mantıksal Görünüm ) seçilir. Şablona daha fazla Soda komutu ekleyelim: 10. Şablon görünümünün sağ tarafındaki Name (İsim) ve Documentation (Belgeleme) sekmeleri tıklanır. Bu seçimler komut ağacındaki komutlara iki DISPLAY komutu ekler. 11. Sağ taraftaki Classes (sınıflar) sekmesi tıklanır. The SoDA TemplateView: Class Selection ( Soda şablon görünümü : sınıf seçimi ) diyalog kutusu açılır. Varsayılanı seçmek için OK butonuna tıklanır. 12. Şablon görünümünün sağ tarafındaki Name (İsim) ve Documentation (Belgeleme) sekmeleri tekrar tıklanır. 13. Kullanılabilir değerler listesinden MyOperations seçilir. Daha sonra tekrar Name (İsim) ve Documentation (Belgeleme) tıklanır. 14. Hazırlanan şablon, Word menusunden Soda\tutorial klasörüne Custom.doc olarak kaydedilir. 15. Soda menusunden Generate Report (Rapor Yarat) sekmesi seçilerek rapor yaratılır. Performansı arttırmak için Word minimize edilmiş durumdadir. Oluşan rapor aşağıdaki gibi bir görünüm alır:
4. Kaynaklar http://www-128.ibm.com/developerworks//rational/library/05/726_us/index.html http://www.ibm.com/support/us/ \Rational Soda\help\tutorial