Yazılım Stajı İçin GitHub README Nasıl Yazılır? Bölüm Bölüm Örnek

Yazılım stajı için GitHub README nasıl yazılır sorusunun kısa cevabı şudur: iyi bir README projenin ne yaptığını, nasıl çalıştırıldığını, hangi teknolojilerle yapıldığını, örnek çıktısını ve bilinen sınırlılıklarını düzenli bir sırayla gösterir. Yalnızca "Python, SQLite, Flask" gibi bir teknoloji listesi bu işi görmez; okur her teknolojinin neden seçildiğini ve projeyi kendi bilgisayarında nasıl çalıştıracağını da görmek ister.

Bu yazıda kurgusal bir konsol uygulaması üzerinden README'yi bölüm bölüm kuruyoruz. Her bölümü kendi projene uyarlayabileceğin bir şablon olarak kullanabilirsin.

README Neden Kullanım Kılavuzudur ve Hangi Sırayla Yazılmalı?

README dosyasını okuyan kişi projeyi hiç görmemiştir. Aklındaki sorular üçtür: bu ne, nasıl çalıştırırım, çalıştırınca ne bekleyeceğim? GitHub, deponun kök klasöründeki (ya da docs veya .github klasöründeki) README dosyasını depoyu ziyaret edenlere otomatik gösterir; README.md uzantısı da dosyanın Markdown ile yazıldığını ve GitHub'da biçimlenmiş hâliyle görüntülendiğini belirtir. Ayrıntılar için GitHub Docs'taki README sayfasına bakabilirsin.

README, projenin reklam metni değil, başka bir kişinin projeyi anlayıp çalıştırmasını sağlayan kullanım kılavuzudur.

Bu bakış açısı yazım sırasını da belirler. Önce projenin amacı gelir, ardından okurun yapacağı işlerin sırası: kurulum, kullanım, örnek çıktı. Proje içi ayrıntılar ve kendi değerlendirmen en sona kalır. Önerilen sıra şöyle:

1. Proje amacı (başlık ve tek cümlelik açıklama)
2. Kurulum
3. Kullanım
4. Örnek çıktı
5. Klasör yapısı
6. Öğrenilenler
7. Geliştirme fikirleri

Bu liste makalenin devamındaki bölümlerle aynı sırayı izler. Her başlıkta o bölümün örnek README'deki karşılığını göreceksin. Tek bir dilin adı ya da teknoloji listesi "ne" sorusunu bile tam yanıtlamaz; "neden bu araç" ve "nasıl çalıştırılır" kısımları eksik kalır. Projeni hangi alana yönelik hazırlayacağını netleştirmek istersen ücretsiz kariyer testi ilgi alanlarını görmen için bir başlangıç noktası olabilir.

Başlık ve Tek Cümlelik Açıklama Nasıl Yazılır?

Başlık projenin adıdır. Hemen altındaki tek cümle "kim için, ne yapar" sorusunu yanıtlar. "Python projesi" bir dil adıdır, açıklama sayılmaz. "Terminalde görev ekleyip listeleyen ve tamamlandı olarak işaretleyen konsol uygulaması" ise okura ne göreceğini söyler.

Örnekler için gorev-cli adında kurgusal bir proje düşünelim. Yalnızca bu yazı için uydurulmuş bir örnektir, gerçek bir depo değildir. Standart kütüphane dışında hiçbir paket kullanmayan, görevleri bir JSON dosyasında tutan küçük bir Python uygulamasıdır. README dosyasının ilk parçası şöyle görünebilir:

# gorev-cli

Terminalde görev ekleyip listeleyen ve tamamlandı olarak işaretleyen konsol uygulaması.

## Kullanılan teknolojiler

- Python 3: ek paket gerektirmeden her makinede çalışsın diye seçildi.
- json (standart kütüphane): görevler okunabilir bir dosyada saklanıyor.
- unittest (standart kütüphane): ek kurulum olmadan test yazabilmek için.

Bu proje kurgusal bir örnektir.

Teknoloji satırında sürüm numarası yok; sürümü projenin gerçekten çalıştığı ortama göre kendi README'ne ekleyebilirsin. Asıl fark gerekçelerdedir. "Python, JSON, unittest" yazan bir satır okura yalnızca isim verir. Her adın yanındaki kısa gerekçe ise seçimlerini savunabildiğini gösterir. Gerekçe bulamıyorsan o teknolojiyi neden kullandığını yeniden düşünmen için iyi bir işarettir.

Kurulum, Test Komutu ve Örnek Kullanım Sırayla Nasıl Anlatılır?

Kurulum bölümünü, projeyi hiç görmemiş birinin sıfırdan bir makinede adım adım izleyeceği şekilde yaz: önkoşullar, projeyi indirme, varsa bağımlılık kurulumu, çalıştırma, test, örnek kullanım. Üç ilke işini görür:

• Her komut ayrı satırda olsun ve tek iş yapsın.
• Komutun hangi klasörde çalıştırılacağını yaz.
• "Bende çalışıyor" varsayımlarından kaçın: kendi makinene önceden kurduğun paketleri, ortam değişkenlerini ya da dosyaları okur da bilir sanma.

Kurgusal gorev-cli için kurulum parçası şöyle olabilir. Komutlar, kod çiti kullanılmadan dört boşluk girintili blok olarak yazılmıştır:

## Kurulum

Önkoşul: Python 3 kurulu olmalı.

    python --version

Beklenen sonuç: terminal bir Python sürümü yazdırır.

Projeyi indir (kurgusal adres):

    git clone https://github.com/kullanici-adi/gorev-cli.git

Beklenen sonuç: gorev-cli klasörü oluşur.

Proje klasörüne gir:

    cd gorev-cli

Bu uygulama ek paket kullanmadığı için bağımlılık kurulumu yoktur.

## Testleri çalıştırma

Aşağıdaki komutu gorev-cli klasöründe çalıştır:

    python -m unittest

Beklenen sonuç: son satırda OK yazar.

## Örnek kullanım

Komutları yine gorev-cli klasöründe çalıştır:

    python gorev.py ekle "Rapor yaz"

Beklenen sonuç: Eklendi: 1. görev

    python gorev.py tamamla 1

Beklenen sonuç: Tamamlandı

    python gorev.py listele

Beklenen sonuç: 1. [x] Rapor yaz

Bu örnekteki test komutu, standart kütüphanedeki unittest modülünü komut satırından çalıştırır. Argüman verilmediğinde test dosyalarını bulup çalıştırdığı Python belgelerindeki unittest sayfasında anlatılıyor. Bazı sistemlerde python yerine python3 yazman gerekebilir; README'de bunu bir cümleyle belirtmek okurun vakit kaybetmesini önler.

Kendi projende temiz klasör denemesi

README'deki komutların gerçekten yeterli olup olmadığını şu adımlarla sına:

1. Projeni boş bir klasöre, README'de yazdığın indirme komutuyla yeniden indir.
2. Yeni bir terminal aç ve yalnızca README'deki komutları, yazdığın sırayla çalıştır.
3. Bir komut hata verirse sorunu README'ye eksik adım olarak ekle.
4. Her komutun yazdığın "beklenen sonuç" satırıyla örtüşüp örtüşmediğine bak.

Bu deneme birkaç dakika sürer ve "bende çalışıyor" varsayımlarının çoğunu ortaya çıkarır.

Ekran Görüntüsü Yerine (ya da Yanında) Metin Çıktısı Nasıl Kullanılır?

Konsol uygulamasında örnek çıktıyı kod bloğu içinde metin olarak ver. Metin kopyalanabilir ve aranabilir. Kodla aynı depoda durduğu için sürümle birlikte güncellenir, ayrıca görsel dosyası yönetmeni gerektirmez. Arayüzü olan projelerde ise ekran görüntüsü yerindedir. Bu iki yöntem birbirinin yerine geçen tek doğru değil, projenin türüne göre seçilen araçlardır.

GitHub, README içindeki kod bloğunu üç ters tırnak arasına alınan metinle oluşturur. Ayrıntıları GitHub Docs: Creating and highlighting code blocks sayfasında bulabilirsin. Görsel için de yöntem var: GitHub, .md dosyalarına görsel eklemeyi destekler. Görsel depodaysa göreli bağlantı kullanman önerilir. Markdown'da görsel; ünlem işareti, köşeli parantez içindeki alternatif metin ve parantez içindeki dosya yoluyla eklenir.

Ekran görüntüsü kullanacaksan yanına bir iki cümlelik açıklama yaz. Görüntüde neye bakılması gerektiğini söyle. Alternatif metni boş bırakma. Konsol uygulamasında bile renkli ya da tablo biçimli çıktı varsa, metin bloğunun yanında tek bir görüntü ekleyebilirsin.

Kurgusal görev takip uygulamamızın README'sindeki "Örnek çıktı" parçası aşağıdaki gibi olabilir. Bu parça README'de üç ters tırnakla açılan bir blokun içinde durur. Her komut $ ile başlar, altındaki satırlar o komutun çıktısıdır:

$ python gorev.py ekle "Rapor taslağını yaz"
Eklendi: #1 Rapor taslağını yaz

$ python gorev.py ekle "Testleri çalıştır"
Eklendi: #2 Testleri çalıştır

$ python gorev.py tamamla 1
Tamamlandı: #1

$ python gorev.py listele
[x] 1  Rapor taslağını yaz
[ ] 2  Testleri çalıştır

$ python gorev.py tamamla 9
Hata: 9 numaralı görev bulunamadı.

Hata durumunu da göstermek, uygulamanın sınırını okura ilk bakışta anlatır. Komutun adı, parametresi ya da çıktı biçimi değiştiğinde bu bloğu da güncelle. Kodla uyuşmayan bir örnek, hiç örnek olmamasından daha çok kafa karıştırır. Yayınlamadan önce komutları kendi makinende baştan çalıştırıp çıktıyı karşılaştırabilirsin.

Klasör Yapısı ve Teknik Kararların Gerekçesi Nasıl Yazılır?

Klasör yapısını ağaç biçiminde, kısa bir blokta göster. Her dosyanın yanına tek satırlık görev yaz; her küçük dosyayı saymana gerek yok. Teknik kararlar bölümünde ise "ne yaptım" değil "neden bunu seçtim ve neyi göze aldım" sorusunu yanıtla.

gorev-takip/
├── gorev.py          komut satırı girişi, komutu ilgili fonksiyona yönlendirir
├── komutlar.py       ekle, listele ve tamamla fonksiyonları
├── depo.py           görevleri JSON dosyasından okur, dosyaya yazar
├── tests/
│   └── test_komutlar.py   komut fonksiyonlarının birim testleri
├── gorevler.json     çalışırken oluşan veri dosyası (depoya eklenmez)
└── README.md

Bir karar için gerekçe yazarken alternatifi ve takası da belirt. Aşağıdaki küçük çerçeve bunu düzenli yapmana yardım eder:

Aynı bilgiyi README'de kısa bir "Teknik kararlar" bölümü olarak yazabilirsin. Gerçek README'de bunları madde işaretli liste yapabilirsin:

Veriyi JSON dosyasında tuttum: proje küçük ve ek kurulum gerektirmiyor. Aynı anda birden fazla kullanıcı olursa veri tabanı gerekir.
Harici kütüphane kullanmadım: kurulum adımı kısa kalsın istedim. Bunun karşılığında argüman ayrıştırmayı elle yazdım.
Komutları ayrı fonksiyonlara böldüm: her birini testle ayrı ayrı deneyebiliyorum.

Her kararı yazmak zorunda değilsin. Bir okurun "neden böyle?" diye soracağı iki üç karar yeterlidir.

Öğrenilenler, Bilinen Sınırlılıklar ve Geliştirme Fikirleri Nasıl Dürüst Yazılır?

Dürüst yazmak, projenin bugünkü durumunu ölçülebilir ve doğrulanabilir cümlelerle anlatmaktır. Beş ölçüt işini görür:

• Somut ol: "Girdi doğrulaması yalnızca boş metni yakalıyor" gibi, birinin deneyip doğrulayabileceği cümleler kur.
• Olmayanı varmış gibi yazma: Yazdığın her özelliği README'deki komutla çalıştırabilmelisin.
• Sınırlılığı kusur gibi değil, mevcut durum olarak yaz: "Şu an tek kullanıcıyı destekliyor" yeterlidir.
• Geliştirme fikrini yapılmış gibi yazma: "Yapılabilir" ya da "eklenebilir" gibi kiplerle ayır.
• Öğrendiğini projede karşılaştığın bir sorunla bağla: "Dosya işlemlerini öğrendim" yerine hangi hatayla karşılaştığını ve nasıl çözdüğünü yaz.

Abartılı ve dürüst cümleler arasındaki fark şöyle görünür:

• Abartılı: "Kapsamlı hata yönetimi var." Dürüst: "Geçersiz görev numarası ve boş metin yakalanıyor; çok uzun metinler denetlenmiyor."
• Abartılı: "Hızlı ve ölçeklenebilir." Dürüst: "Her komutta dosyanın tamamı okunup yazılıyor; çok sayıda görevle denenmedi."
• Abartılı: "Çok kullanıcılı kullanıma uygun." Dürüst: "Tek kullanıcı için tasarlandı; iki işlem aynı anda yazarsa kayıt kaybolabilir."

Kurgusal görev takip uygulamasının üç parçası şöyle olabilir. Bunlar yalnızca bu örnek proje için yazılmıştır, gerçek bir öğrenci deneyimi değildir:

Öğrenilenler
Türkçe karakterli görevler JSON dosyasına kaçış dizisi olarak yazılıyordu. json.dump çağrısında ensure_ascii=False kullanıp dosyayı UTF-8 olarak açınca dosya okunur hâle geldi.
İlk çalıştırmada gorevler.json yoktu ve program hata verdi. depo.py dosya yoksa boş liste döndürüyor.
Komutları tek dosyada tutunca test yazmak zorlaştı. Fonksiyonlara ayırınca her komutu ayrı test edebildim.

Bilinen sınırlılıklar
Girdi doğrulaması yalnızca boş metni yakalıyor.
Görevi silme komutu yok, yalnızca tamamlandı olarak işaretlenebiliyor.
Aynı anda iki işlem dosyaya yazarsa kayıt kaybolabilir.

Geliştirme fikirleri
Silme komutu eklenebilir.
Göreve son tarih alanı eklenebilir.
Veri, çok kullanıcı gerekirse bir veri tabanına taşınabilir.

Geliştirme fikirleri bölümü kısa kalsın. Bu bölüm yol haritası vaadi değil, projenin nereye açılabileceğine dair bir not olmalı.

Yayınlamadan Önce Kontrol Listesi ve Sık Yapılan Hatalar

Depoyu herkese açmadan önce aşağıdaki soruları kendi projene sor. Her maddenin cevabı "evet" ya da "hayır" olmalı; "hayır" çıkan maddeyi düzeltip listeye geri dön.

Proje amacı ve kurulum

• Başlığın hemen altında projenin ne yaptığını anlatan tek bir cümle var mı?
• Projenin hangi dille ve hangi temel araçlarla yazıldığı belirtilmiş mi?
• Gereken sürüm ya da ön koşullar (örneğin yorumlayıcı veya derleyici sürümü) yazılmış mı?
• Kurulum adımları, depoyu indirmekten ilk çalıştırmaya kadar sırayla yazılmış mı?
• Varsa test komutu README'de duruyor mu?

Kullanım ve örnek çıktı

• En az bir örnek kullanım komutu, kopyalanıp çalıştırılabilecek biçimde verilmiş mi?
• Bu komutun gerçek çıktısı metin olarak ya da görselle gösterilmiş mi?
• Çıktı, kodun şu anki hâlinden mi alınmış?

Klasör yapısı ve teknik kararlar

• Ana klasör ve dosyalar kısa birer açıklamayla listelenmiş mi?
• Seçtiğin kütüphane ya da veri saklama yönteminin gerekçesi bir iki cümleyle yazılmış mı?

Öğrenilenler ve geliştirme fikirleri

• Projede zorlandığın bir konuyu ve nasıl çözdüğünü yazdın mı?
• Bilinen sınırlılıklar açıkça belirtilmiş mi?
• Geliştirme fikirleri, yapılmış işlerden ayrı bir başlık altında mı?

Üç sık hata

Kurulumsuz README: Proje anlatılmış ama nasıl çalıştırılacağı yazılmamıştır. Okuyan kişi kodu indirir, hangi dosyayı hangi komutla başlatacağını bulamaz ve projeyi denemeden bırakır. Çözüm basit: kurulum ve ilk çalıştırma için iki üç satırlık bir komut dizisi ekle.

Abartılı iddia: "Çok hızlı", "profesyonel", "tam kapsamlı" gibi ölçülemeyen sıfatlar ve henüz yazılmamış özellikler README'ye güven kaybettirir. Bunların yerine ölçülebilir ya da gösterilebilir ifadeler kullan: "Kayıtları JSON dosyasında saklar", "Üç komutu destekler". Planlanan özellikleri yapılmış gibi değil, geliştirme fikirleri başlığında yaz.

Güncel olmayan komut: Kod değişmiş, README aynı kalmıştır; dosya adı değişmiş ya da yeni bir bağımlılık eklenmiştir. Çözüm, README'yi yayınlamadan önce temiz bir klasöre depoyu yeniden indirip yazdığın komutları sırayla kendin denemektir. Bir komut hata verirse okuyan kişi de aynı hatayı görür.

Sık Sorulan Sorular

README Türkçe mi İngilizce mi yazılmalı?

Projeyi kimin okuyacağına göre seç. Başvuruyu Türkçe konuşan ekiplere yapıyorsan Türkçe yeterlidir. Uluslararası bir ortamı hedefliyorsan İngilizce yazabilir ya da kısa bir İngilizce özet ekleyebilirsin. Hangisini seçersen seç, dili tek bir dosyada tutarlı kullan.

Konsol uygulamasında ekran görüntüsü şart mı?

Şart değil. Konsol çıktısını kod bloğu olarak metin biçiminde eklemek de aynı işi görür; üstelik kopyalanabilir ve aranabilir. Ekran görüntüsünü isteğe bağlı bir ek olarak kullanabilirsin.

Küçük bir proje için README ne kadar uzun olmalı?

Sabit bir uzunluk yok. Amaç, kurulum, örnek kullanım ve çıktı, klasör yapısı ile sınırlılıklar eksiksiz yer alıyorsa birkaç ekranlık bir dosya yeterli olabilir. Bir bölüm yeni bilgi vermiyorsa çıkar, okuyanın çalıştırmak için ihtiyaç duyduğu bir adım eksikse ekle.

Bu listeyi uygulamak için büyük bir proje beklemene gerek yok; elindeki en küçük projeyi seçip README'sini bu sırayla yazman yeterli. Yeni projelere geçtikçe bu düzeni tekrar kullanabilirsin. Yazılım ve kariyer üzerine diğer yazılara da Berk Akademi blog sayfasından ulaşabilirsin.