Projeyi Belgelemek

Bir cümlelik özet

Belgeleme, bir projeyi seni tanımayan birinin bile anlayıp tekrar yapabileceği şekilde yazıya, şemaya ve fotoğrafa dökmektir.

Neden önemli?

Bir projeyi bitirdiğinde onu sadece sen ve o an aklında olanlar bilir. Aradan iki ay geçtiğinde çoğu ayrıntıyı sen bile unutursun: hangi pini kullandığını, direncin kaç ohm olduğunu, kodun neden o satırda düzeltildiğini.

Belgeleme bu unutmayı engeller. İyi bir belge üç işe yarar:

• Başkası anlar. Bir arkadaşın, öğretmenin ya da bir yarışma jürisi projeni senin yardımın olmadan takip edebilir.
• Sen devam edebilirsin. Projeye aylar sonra döndüğünde nereden başlayacağını bilirsin.
• Öğrenmen kanıtlanır. Önceki derste iyileştirme yaptın; belge, o iyileştirmenin öncesini ve sonrasını gösteren kayıttır.

Belgeleme yeni bir programlama konusu değildir. Bir yöntemdir. Kod yazmak kadar önemli bir mühendislik becerisidir ve çoğu zaman en çok atlanan adımdır.

Bu derste tek bir örnek proje üzerinden ilerleyeceğiz: otomatik gece lambası. Karanlık olduğunda LED'i yakan, aydınlık olduğunda söndüren küçük bir devre. Önceki modüllerde bu tür bir projeyi kurmuştuk; şimdi onu belgelemeyi öğreniyoruz.

Bir belge hangi parçalardan oluşur?

İyi bir proje belgesi rastgele notlardan değil, belli bir sıradan oluşur. Bu sıra aslında projeyi yaparken izlediğin yolun aynısıdır: problem, çözüm, malzeme, yapım, test, sonuç, sonraki adım.

Problemden sonuca giden zincir

Her bölüm bir soruya cevap verir:

• Problem: Neyi çözmeye çalıştın?
• Çözüm fikri: Nasıl çözmeyi düşündün?
• Malzeme: Neye ihtiyaç vardı?
• Kod ve şema: Nasıl kurdun ve programladın?
• Test: Gerçekten çalıştı mı, nasıl denedin?
• Sonuç: Ne oldu, ne kadar iyi çalıştı?
• Sonraki adım: Bir dahaki sefere neyi değiştirirdin?

Bu zincir, "öğrenme kanıtı" yapısıyla birebir örtüşür. Öğrenme kanıtı, bir şeyi öğrendiğini gösteren somut izdir. Belge de tam olarak budur: sadece "yaptım" demezsin, nasıl yaptığını ve ne öğrendiğini gösterirsin.

Örnek 1: Gece lambası için problem ve çözüm

Belgenin ilk iki bölümünü gece lambası için şöyle yazabiliriz:

Problem: Gece yarısı su içmeye kalktığımda büyük ışığı açmak gözümü çok yoruyordu ve odadaki kardeşimi uyandırıyordu. Çözüm fikri: Karanlığı algılayan bir ışık sensörü (LDR) ile küçük bir LED'i otomatik yakan bir devre kurmak. Ortam karardığında LED yansın, aydınlanınca sönsün.

Dikkat et: iddialı değil, dürüst bir dil. "Kusursuz bir sistem kurdum" demiyoruz; gerçek bir ihtiyaçtan yola çıkıyoruz.

Örnek 2: Malzeme listesini tabloyla yazmak

Malzemeyi cümlelerle anlatmak yerine tabloya koymak çok daha okunaklıdır. Buna malzeme listesi (bill of materials) denir:

Biri bu tabloya bakarak aynı parçaları toplayıp projeni tekrar kurabilir. İyi bir malzeme listesinin amacı budur.

README: Bir proje dosyasının kapağı

Yazılım dünyasında her projenin bir README dosyası olur. "Read me" yani "beni oku" demektir. Projeyi açan ilk kişinin ilk gördüğü, kısa ve düzenli bir tanıtım metnidir.

README, uzun bir rapor değildir. Projeyi bilmeyen birinin bir dakikada ne olduğunu anlamasını sağlar.

İyi bir README'de neler bulunur?

• Projenin adı ve tek cümlelik açıklaması
• Ne işe yaradığı
• Hangi malzeme veya kütüphaneye ihtiyaç olduğu
• Nasıl kurulup çalıştırıldığı
• Bir fotoğraf veya kısa video bağlantısı
• Sonraki adımlar

Gece lambası README taslağı

# Otomatik Gece Lambası

Karanlık olduğunda otomatik yanan, aydınlıkta sönen küçük bir LED lambası.

## Ne yapar?
Ortamdaki ışığı bir LDR sensörüyle ölçer. Işık belli bir eşiğin
altına düşerse LED yanar.

## Gerekenler
- Arduino Uno
- LDR, LED, 220 ohm ve 10K ohm direnç
- Breadboard ve jumper kablolar

## Nasıl çalıştırılır?
1. Devreyi şemaya göre kur.
2. gece_lambasi.ino dosyasını Arduino'ya yükle.
3. Odayı karart ve LED'in yandığını gözle.

## Test sonucu
Işık eşiği 400 olarak ayarlandı. El ile sensörü kapatınca
LED gecikmeden yandı.

## Sonraki adım
Eşik değerini bir potansiyometreyle ayarlanabilir yapmak.

Bu taslak kısa ama eksiksiz. Biri onu okuyup projeyi anlayabilir ve tekrar kurabilir.

Belgede test ve sonucu göstermek

Bir projenin en değerli parçası, çalıştığını nasıl kanıtladığındır. Belge sadece "çalışıyor" demez; hangi durumu denediğini ve ne gördüğünü yazar. Bunun için küçük bir test senaryosu tablosu kullanabilirsin:

Son satır önemlidir. Titreme bir "hata" değil, gözlemdir. Onu dürüstçe yazmak, bir sonraki iyileştirmenin (sınır durumu için bir gecikme eklemek gibi) başlangıç noktası olur. Belgeleme başarıyı süslemek için değil, ne olduğunu doğru kaydetmek içindir.

Mini uygulama

Kendi seçtiğin küçük bir projeyi (gece lambası, çizgi izleyen robot ya da bir Scratch oyunu olabilir) belgelemek için aşağıdaki proje dosyası içindekiler şablonunu doldur:

PROJE DOSYASI ŞABLONU
=====================
1. Proje adı: _______________________
2. Problem (1-2 cümle): _______________
3. Çözüm fikri: _______________________
4. Malzeme listesi (tablo): ___________
5. Kod / şema: ________________________
6. Test senaryoları (tablo): __________
7. Sonuç (ne oldu): ___________________
8. Sonraki adım: ______________________
9. Fotoğraf / video notu: _____________

Her satırı doldurabiliyorsan projeni başkası da anlayabilir demektir. Boş kalan satır varsa, muhtemelen o parçayı henüz kimseye anlatamıyorsundur; en çok orayı çalışman gerekir.

Uygulama laboratuvarı: Projeyi Belgelemek

Projeyi Belgelemek konusunu kalıcı hâle getirmenin en iyi yolu, kavramı küçük ve ölçülebilir bir göreve dönüştürmektir. Bu çalışmada Bir belge hangi parçalardan oluşur? ile Örnek 1: Gece lambası için problem ve çözüm arasındaki ilişkiyi kullanarak sorun tanımı, gereksinim listesi, prototip, test kaydı ve kısa sunum hazırlayacaksın. Amaç yalnız sonucun çalışması değil; hangi kararı neden verdiğini, neyi test ettiğini ve hangi durumda tasarımı değiştireceğini açıklayabilmektir.

Görev senaryosu

Şu senaryoyu ele al: başarısız denemeleri de belgeleyen dürüst proje günlüğü oluşturma. Dersin ana hedefi “Projeni başkasının anlayıp tekrarlayabileceği şekilde belgelemeyi ve bir README yazmayı öğren” olduğuna göre önce problemi tek cümleyle tanımla. Ardından sistemin alacağı girdiyi, uygulayacağı işlemi ve üreteceği çıktıyı ayrı ayrı yaz. Bilmediğin bir ayrıntı varsa onu varsayım olarak işaretle; varsayımı gerçek bilgi gibi kullanma.

1. Planla: Başlangıç durumunu, beklenen sonucu ve kullanacağın kavramları yaz.
2. En küçük sürümü kur: Yalnız temel davranışı çalıştır; süsleme ve ek özellikleri sonraya bırak.
3. Üç test hazırla: Normal bir durum, sınırda bir durum ve hatalı ya da beklenmeyen bir durum seç.
4. Sonucu kaydet: Beklenen ile gerçekleşeni yan yana yaz; fark varsa olası nedeni belirt.
5. Tek değişiklik yap: Aynı anda birçok şeyi değiştirmek yerine bir kararı düzeltip testi yeniden çalıştır.

Başarı ölçütleri

• Sorun ve kullanıcı tek cümlede tanımlı mı?
• Gereksinimler ölçülebilir mi?
• Prototip en riskli varsayımı gerçekten deniyor mu?
• Test sonucu tarih ve koşulla kaydedildi mi?
• Sunumda çalışmayan noktalar da dürüstçe açıklanıyor mu?

“Projeyi Belgelemek” çalışmasını bitirdiğinde ürünü bir arkadaşına yalnız bölüm başlıklarıyla anlat. Arkadaşın başarısız denemeleri de belgeleyen dürüst proje günlüğü oluşturma senaryosundaki adımları ve karar nedenlerini takip edebiliyorsa anlatım yeterince açıktır. Anlaşılmayan noktayı daha fazla terim ekleyerek değil, Bir belge hangi parçalardan oluşur? ve Örnek 1: Gece lambası için problem ve çözüm ilişkisini daha küçük adımlara bölerek düzelt.

Sık yapılan hatalar

Her şeyi akılda tutmaya çalışmak

"Nasılsa hatırlarım" en sık yapılan hatadır. Ayrıntılar birkaç gün içinde silinir. Belgeyi proje biterken değil, proje sürerken tut.

Sadece çalışan halini yazmak

Denemelerini, başarısız halini ve düzeltmeyi de yaz. "İlk devrede LED hiç yanmadı, direnci yanlış bacağa takmışım" gibi notlar belgeni gerçek ve öğretici yapar.

Malzemeyi belirsiz yazmak

"Bir direnç" yeterli değildir. Kaç ohm olduğunu yaz. Başkası aynı projeyi ancak net değerlerle kurabilir.

Ekran görüntüsü ve fotoğraf koymamak

Bir fotoğraf, üç paragraflık açıklamadan daha hızlı anlatır. Devrenin ve çalışan halin fotoğrafını eklemeyi unutma.

Güvenlik notu

Belgeye fotoğraf veya video eklerken kişisel bilgilerini koru:

• Yüz ve isim: Kendi ya da başkasının yüzünü, tam adını, okul adını kareye alma. Bir kişinin görüntüsünü paylaşacaksan önce izin al; küçük bir kardeşin veya arkadaşın varsa velisinden de.
• Ev bilgisi: Ev adresini, kapı numarasını, sokak tabelasını fotoğrafa alma. Arka planda görünen özel eşyalara dikkat et.
• Paylaşım: Belgeni internette paylaşmadan önce bir yetişkine göster. Projeyi anlatmak için genelde sadece devrenin ve ekranın görüntüsü yeterlidir; kişisel ortam görünmesine gerek yoktur.

Amaç, projeni gururla paylaşabilmen ama bunu güvenli bir şekilde yapmandır.

Ders özeti

• Belgeleme, projeni başkasının anlayıp tekrar yapabileceği hale getirmektir.
• İyi bir belge problem, çözüm, malzeme, kod/şema, test, sonuç ve sonraki adım sırasını izler; bu sıra öğrenme kanıtı yapısıyla örtüşür.
• README, projenin bir dakikada anlaşılmasını sağlayan kısa tanıtım dosyasıdır.
• Malzeme ve test gibi bilgileri tablo halinde yazmak okunabilirliği artırır.
• Fotoğraf ve video eklerken yüz, isim ve ev bilgisi gibi kişisel verileri koru ve izin al.

Kontrol soruları

1. Belgelemenin üç temel faydasını yaz.
2. Bir proje belgesindeki yedi ana bölümü sırayla say.
3. README dosyası ne işe yarar ve adı ne anlama gelir?
4. Malzeme listesini tabloyla yazmak neden düz cümleden daha iyidir?
5. Bir projenin fotoğrafını paylaşırken hangi üç kişisel bilgiye dikkat etmelisin?

Cevaplar

1. Başkasının projeyi anlaması, senin aylar sonra devam edebilmen ve öğrenmenin kanıtlanması.
2. Problem, çözüm fikri, malzeme, kod/şema, test, sonuç, sonraki adım.
3. README ("beni oku") projeyi açan kişinin ilk gördüğü kısa tanıtımdır; projenin ne olduğunu, nasıl kurulup çalıştırıldığını hızla anlatır.
4. Tablo, parçaları adet ve değerleriyle net gösterir; okuyan kişi aynı parçaları kolayca toplayıp projeyi tekrar kurabilir.
5. Yüz ve tam isim, ev adresi/kapı numarası gibi konum bilgisi, arka planda görünen özel eşyalar; ayrıca başkasını paylaşacaksan izin almak.

Kaynak ve doğrulama notu

“Projeyi Belgelemek” dersi için doğrulama odağı Bir belge hangi parçalardan oluşur? ile Örnek 1: Gece lambası için problem ve çözüm arasındaki ilişkinin örnekler üzerinde tutarlı çalışmasıdır. Proje sayfalarında sonuç iddiası ancak gerçek prototip, test kaydı veya gözlemle desteklendiğinde kullanılmalıdır. Maliyet, süre ve başarı oranı gibi sayılar tahminse açıkça “tahmin” olarak işaretlenmelidir.

Sonraki ders

Sunum Hazırlamak: Belgelediğin projeyi bir dinleyici önünde kısa ve anlaşılır biçimde anlatmayı öğren.