Topluluk katkılarını kabul eden, net iş akışları, inceleme adımları ve güvenilir yayınlama içeren açık kaynak proje sitesi nasıl planlanır, oluşturulur ve sürdürülür öğrenin.
Bir tema seçmeden veya ana sayfa taslağı çizmeden önce sitenin ne için olduğunu belirleyin. Açık kaynak siteleri genellikle aynı anda her şeye hizmet etmeye çalışır—doküman portalı, pazarlama sayfası, topluluk merkezi, blog, bağış akışı—ve sonunda hiçbirini iyi yapamazlar.
Sitenin yerine getirmesi gereken en önemli 1–3 işi yazın. Yaygın örnekler:
Sitenin amacını bir cümlede açıklayamıyorsanız, ziyaretçiler de yapamaz.
Ana hedef kitlelerinizi ve her grubun yapmasını istediğiniz “ilk tıklamayı” listeleyin:
Yararlı bir egzersiz: her kitle için gelen ilk 3 soruyu yazın (ör. “Nasıl kurulur?”, “Bu aktif mi?”, “Hata nerede bildirilir?”).
Hedeflerinize bağlı, izlemesi gerçekçi basit metrikler seçin:
Sitenin yapmayacağı şeyleri açıkça listeleyin (şimdilik): özel web uygulamaları, karmaşık hesap sistemleri, ağır entegrasyonlar veya özel CMS özellikleri. Bu, bakıcıların zamanını korur ve projeyi gönderilebilir tutar.
İçeriği iki kovana ayırın:
Bu tek karar ileride araç seçimlerinizi, inceleme iş akışınızı ve katkı deneyimini şekillendirir.
Topluluk sitesi hızla dağılabilir; “siteye neyin ait olduğu” ile repodaki içeriğin nerede tutulacağına karar vermezseniz. Araçlar ve temalar öncesinde basit bir yapı ve net bir içerik modeli konusunda anlaşın—böylece katkıcılar nerede ekleme yapacaklarını bilir ve bakıcılar nasıl inceleyeceklerini bilirler.
Birincil navigasyonu kasıtlı olarak sade tutun. Açık kaynak proje sitesi için iyi bir varsayılan sitemap:
Bir sayfa bunlardan birine uymuyorsa, bu bilginin repoda daha uygun olduğunu veya yeni bir içerik türüne ihtiyaç olduğunu gösterir.
README’yi geliştiriciye yönelik temel bilgiler için kullanın: derleme talimatları, yerel geliştirme kurulumu, testler ve kısa proje durumu. Siteyi ise şunlar için kullanın:
Bu ayrım, içeriğin aynı anda iki yerde sürüklenip uyumsuzlaşmasını önler.
Alan bazında (içerik sahipleri) atama yapın (dokümanlar, blog/haber, çeviriler). Sahiplik tek bir engelleyici olmak zorunda değil; küçük bir grup, net inceleme sorumluluğu ile olabilir.
Küresel bir topluluğa dost bir ton ve stil rehberi yazın: yalın dil, tutarlı terimler ve ana dili İngilizce olmayan yazarlar için rehberlik.
Projeniz sürümler yayıyorsa, erken dönemde versiyonlu dokümanlar planlayın (ör. “latest” ve desteklenen sürümler). Birden fazla sürüm çıktıktan sonra yapıyı sonradan değiştirmek zordur.
Web sitesi yığını, birinin bir yazım hatasını düzeltmesini, yeni bir sayfa eklemesini veya dokümanı geliştirmesini kolaylaştırmalı—bir derleme mühendisine dönüşmeden. Çoğu açık kaynak proje için bu şunu gerektirir: Markdown-öncelikli içerik, hızlı yerel kurulum ve sorunsuz bir pull request iş akışı ile önizlemeler.
Düzeni ve navigasyonu hızla iterasyona sokmayı planlıyorsanız, kalıcı bir yığına karar vermeden önce site deneyimini prototiplemeyi düşünün. Platformlar gibi Koder.ai sohbet yoluyla docs/pazarlama sitesi taslağı oluşturmanıza, gerektiğinde backend ile çalışan bir React tabanlı UI üretmenize ve sonra kaynak kodu repoya aktarılacak şekilde dışa aktarmanıza yardımcı olabilir—bu, bilgi mimarisi ve katkı akışlarını haftalar süren kurulum olmadan keşfetmek için faydalıdır.
Aşağıda katkı-odaklı dokümanlar ve proje siteleri için yaygın seçeneklerin durumu:
mkdocs.yml düzenleyin ve tek bir komut çalıştırın.Katkıcıların değişikliklerini yayınlamadan önce canlı görebilmeleri için önizleme derlemelerini destekleyen bir hosting seçin:
Varsa varsayılan yolu “PR aç, önizleme al, inceleme iste, merge et” olacak şekilde kurun. Bu, bakıcıların geribildirimi azaltır ve katkıcı güvenini artırır.
Kısa bir docs/website-stack.md (veya README.md içinde bir bölüm) ekleyin: ne seçtiğinizi ve nedenini; siteyi yerelde nasıl çalıştıracağınızı, önizlemelerin nerede göründüğünü ve hangi değişikliklerin website reposunda olması gerektiğini yazın.
Dostane bir repo, “geçici düzenlemeler” ile sürekli katkı arasında fark yaratır. Gezinmesi kolay, inceleyiciler için öngörülebilir ve yerelde çalıştırması basit bir yapı hedefleyin.
Web ile ilgili dosyaları gruplayın ve açıkça adlandırın. Yaygın bir yaklaşım:
/
/website # pazarlama sayfaları, açılış, navigasyon
/docs # doküman kaynakları (referans, rehberler)
/blog # sürüm notları, duyurular, hikayeler
/static # görseller, simgeler, indirilebilir varlıklar
/.github # issue şablonları, workflow’lar, CODEOWNERS
README.md # repo genel bakışı
Eğer proje zaten uygulama kodu içeriyorsa, siteyi /website (veya /site) içine koyun ki katkıcılar nereden başlayacaklarını tahmin etmesin.
/website içinde odaklı bir README ekleyin/website/README.md oluşturun ve “Değişikliğimi nasıl önizlerim?” sorusuna cevap verin. Kısa ve kopyala-yapıştır yapılabilir olsun.
Örnek quickstart (yığına göre uyarlayın):
# Website quickstart
## Requirements
- Node.js 20+
## Install
npm install
## Run locally
npm run dev
## Build
npm run build
## Lint (optional)
npm run lint
Ayrıca ana dosyaların (navigasyon, footer, yönlendirmeler) nerede olduğunu ve yeni bir sayfa eklemenin nasıl yapılacağını belirtin.
Şablonlar biçim tartışmalarını azaltır ve incelemeleri hızlandırır. Bir /templates klasörü ekleyin (veya /docs/CONTRIBUTING.md içinde şablonları belgeleyin).
/templates
docs-page.md
tutorial.md
announcement.md
Basit bir doküman sayfası şablonu şöyle olabilir:
---
title: "Sayfa başlığı"
description: "Bir cümlelik özet"
---
## Ne öğreneceksiniz
## Adımlar
## Sorun giderme
Belirli alanlarda bakıcılarınız varsa /.github/CODEOWNERS ekleyin ki doğru kişiler otomatik olarak ister yapılsın:
/docs/ @docs-team
/blog/ @community-team
/website/ @web-maintainers
Her araç için bir kanonik konfigürasyon dosyası tercih edin ve kısa neden açıklamaları ekleyin. Hedef, yeni bir katkıcının menü öğesi değiştirebilmesi veya yazım hatasını düzeltebilmesi için tüm build sisteminizi öğrenmesine gerek kalmamasıdır.
Bir web sitesi kod tabanından farklı katkı çeker: metin düzeltmeleri, yeni örnekler, ekran görüntüleri, çeviriler ve küçük UX düzelmeleri. Eğer CONTRIBUTING.md sadece geliştiriciler için yazıldıysa, birçok potansiyel yardımı kaybedersiniz.
CONTRIBUTING.md oluşturun veya ayırın; site değişikliklerine odaklansın: içerik nerede yaşar, sayfalar nasıl üretilir ve “tamam” ne demektir. Kısa bir “yaygın görevler” tablosu (yazım hatası düzeltme, yeni sayfa ekleme, navigasyon güncelleme, blog gönderisi yayınlama) ekleyin ki yeniler dakikalar içinde başlayabilsin.
Var olan daha derin rehberleriniz varsa, bunlara CONTRIBUTING.md üzerinden açıkça bağlayın (örneğin /docs altında bir yürütme sayfası).
Ne zaman önce issue açılmalı, ne zaman doğrudan PR gönderilebileceğini açık belirtin:
Ayrıca “iyi issue şablonu” örneği ekleyin: hangi sayfa URL’si, ne değişecek, okuyucuya nasıl yardımcı olur ve kaynaklar.
Çoğu hayal kırıklığı sessizlikten gelir, geribildirimden değil. Şunları tanımlayın:
Hafif bir kontrol listesi sonradan gidip gelmeyi engeller:
Bir katkı açıldıktan sonra ne olacağı kesinse site sağlıklı kalır. Hedef, öngörülebilir, düşük sürtünmeli ve güvenle yayınlanabilecek bir iş akışıdır.
Bir pull request şablonu ekleyin (ör. .github/pull_request_template.md) ve sadece inceleyicilerin ihtiyaç duyduğu soruları sorun:
Bu yapı incelemeleri hızlandırır ve katkıcılara “iyi” örneği öğretir.
Önizleme dağıtımlarını etkinleştirin ki inceleyiciler değişikliği gerçek site üzerinde görebilsin. Bu, navigasyon güncellemeleri, stil ve düzen hataları için özellikle faydalıdır.
Yaygın desen:
Her PR’de hafif kapılar çalıştırmak için CI kullanın:
Hızlıca başarısız olsun ve açık hata mesajları versin ki katkıcılar bakıcı müdahalesi olmadan düzeltebilsin.
Tek bir kural belgeleyin: PR onaylandıktan ve main’e merge edildikten sonra site otomatik yayımlanır. Elle adımlar veya gizli komutlar olmasın. Kesin davranışı /contributing içinde belirtin ki beklentiler net olsun.
Platformunuz snapshot/rollback destekliyorsa (bazı hostlar yapar, Koder.ai ile deploy ettiğinizde de benzer özellik varsa) “son iyi derleme”nin nerede bulunacağını ve nasıl geri alınacağını belgeleyin.
Dağıtımlar bazen bozulur. Kısa bir geri alma oyun planı belgeleyin:
Sayfalar aynı yerdeymiş gibi hissettirdiğinde topluluk sitesi davetkâr kalır. Hafif bir tasarım sistemi katkıcıların daha hızlı hareket etmesini sağlar, inceleme tartışmalarını azaltır ve büyüdükçe okuyucuları oryante eder.
Küçük bir sayfa “tipi” seti tanımlayın ve bunlara sadık kalın: doküman sayfası, blog/haber yazısı, açılış sayfası ve referans sayfası. Her tip için her zaman görünmesi gerekenleri (başlık, özet, son güncelleme, içerik tablosu, footer linkleri) ve asla olmaması gerekenleri belirleyin.
Navigasyon kurallarıyla netliği koruyun:
sidebar_position veya weight).Katkıcıları “uygun görünmesini sağla” diye zorlamak yerine yapı taşları verin:
Bu bileşenleri kısa bir “Content UI Kit” sayfasında belgeleyin (ör. /docs/style-guide) ve kopyala-yapıştır örnekleri verin.
Asgariyi belirleyin: logo kullanımı (esnemeye veya yeniden renklendirmeye izin yok), 2–3 temel renk ile erişilebilir kontrast, bir veya iki font. Amaç “yeterince iyi”yi kolaylaştırmak, yaratıcılığı sıkı şekilde engellemek değil.
Kurallar üzerinde anlaşın: sabit genişlikler, tutarlı padding ve feature-name__settings-dialog.png gibi adlandırma. Diyagramlar için kaynak dosyalarını tercih edin (ör. Mermaid veya düzenlenebilir SVG) ki güncelleme bir tasarımcı gerektirmesin.
PR şablonuna basit bir kontrol listesi ekleyin: “Bunun zaten bir sayfası var mı?”, “Başlık içinde olduğu bölüme uyuyor mu?”, “Yeni bir üst seviye kategori oluşturacak mı?” Böylece içerik dağılmasını önlerken katkıyı da teşvik edersiniz.
Topluluk sitesi, insanların onu gerçekten kullanabilmesi halinde işe yarar—yardımcı teknolojilerde, yavaş bağlantılarda ve aramalarda. Erişilebilirlik, performans ve SEO’yu sonradan eklenen bir süs değil, varsayılan kabul edin.
Anlamsal yapıyla başlayın. Başlıkları sırayla kullanın (sayfada H1 sonra H2/H3) ve sadece daha büyük yazı için seviyeleri atlamayın.
Metin olmayan içerik için anlamlı alt metin zorunlu kılın. Basit bir kural: bir resim bilgi aktarıyorsa açıklayın; sadece dekoratifse boş alt (alt="") kullanın ki ekran okuyucular atlasın.
Renk kontrastı ve focus durumlarını tasarım token’larınızda kontrol edin. Her etkileşimli öğenin klavye ile erişilebilir olduğundan ve menüler, dialoglar veya kod örneklerinde focus tuzağı olmadığından emin olun.
Görselleri varsayılan olarak optimize edin: maksimum gösterim boyutuna göre yeniden boyutlandırın, sıkıştırın ve build destekliyorsa modern formatları tercih edin. Çoğunlukla metin olan sayfalar için büyük client-side paketleri yüklemekten kaçının.
Üçüncü taraf scriptleri minimumda tutun. Her ekstra widget siteyi yavaşlatır ve herkes için maliyet artırır.
Hostunuzun sağladığı cache varsayılanlarına güvenin (ör. hash’li değişmez varlıklar). Statik site üreticiniz destekliyorsa minify edilmiş CSS/JS üretin ve sadece gerçekten kritik olanı inline edin.
Her sayfaya net bir başlık ve kısa bir meta açıklama verin. Temiz, stabil URL’ler kullanın (tarihler yalnızca gerekiyorsa olsun). Site haritası ve indekslemeye izin veren bir robots.txt oluşturun. Birden fazla doküman versiyonu yayıyorsanız, yinelenen içerikten kaçınmak için bir sürümü “güncel” yapın ve diğerlerine açıkça bağlantı verin.
Analitik ekleyin sadece veriyi kullanacaksanız. Ekliyorsanız, hangi verilerin toplandığını, neden toplandığını ve nasıl opt‑out yapılacağını bir sayfada açıklayın (ör. /privacy).
Son olarak, site içeriği için açık bir lisans bildirimi (kod lisansından ayrıysa) ekleyin. Footer’da ve repository README’sinde belirtin ki katkıcılar metin ve görsellerinin nasıl yeniden kullanılabileceğini bilsin.
Siteinizin temel sayfaları yeni katkıcılar için “gelen yüz”tür. Eğer bu sayfalar hızlıca açık yanıtlar verirse—projenin ne olduğu, nasıl denenebileceği ve nerede yardım gerektiği—daha fazla insan merakı eyleme dönüştürecektir.
Projenin ne yaptığını, kime yönelik olduğunu ve başarı kavramının ne olduğunu açık, sade bir dille anlatan bir özet sayfası oluşturun. Birkaç somut örnek ve “Bu sizin için mi?” kısa bölümü ekleyin.
Ardından momentum için optimize edilmiş bir Quickstart sayfası ekleyin: ilk başarılı çalıştırmaya götüren tek bir yol, kopyala-yapıştır komutlar ve kısa bir sorun giderme bloğu. Kurulum platforma göre değişiyorsa, ana yolu kısa tutup detaylı rehberlere bağlayın.
Önerilen sayfalar:
Tek bir /contribute sayfası şu yönlendirmeleri yapmalı:
/docs/contributing veya etiketli issue kuyruğu)Spesifik olun: bu ay yapılmasını istediğiniz 3–5 görevi adlandırın ve ilgili issue’lara doğrudan bağlantı verin.
Temel belgeleri site üzerinde yayınlayın, repoda gömülü bırakmayın:
/community/meetings)/changelog (veya /releases) ekleyin; tutarlı bir format kullanın: tarih, öne çıkanlar, yükseltme notları ve PR/issue linkleri. Şablonlar bakıcı yükünü azaltır ve topluluk tarafından yazılan notları incelemeyi kolaylaştırır.
Bir showcase sayfası katkıyı motive edebilir, ama güncelliğini yitiren listeler güvenilirliği zedeler. Eğer /community/showcase eklerseniz, hafif bir kural koyun (örn. “üç ayda bir gözden geçir”) ve küçük bir gönderim formu veya PR şablonu sağlayın.
Güncellemeler kolay, güvenli ve ödüllendirici olmalı—ilk defa katkıda bulunanlar için bile. Amaç, “nereye tıklamalıyım?” sürtünmesini azaltmak ve küçük iyileştirmelerin değerli hissettirmesini sağlamaktır.
Dokümanlarda, rehberlerde ve SSS’lerde belirgin bir “Bu sayfayı düzenle” bağlantısı ekleyin. Doğrudan repodaki dosyaya işaret etsin ki PR akışı en az adımdan oluşsun.
Bağlantı metnini dostane tutun (ör. “Yazım hatasını düzelt” veya “Bu sayfayı geliştir”) ve içeriğin üstünde veya altında görünür bir yerde konumlandırın. Eğer katkı rehberi varsa, buradan da bağlayın (örn. /contributing).
Yerelleştirme, klasör yapısının bir bakışta soruyu cevapladığı zaman en iyi çalışır. Yaygın yapı:
İnceleme adımlarını belgeleyin: kim çevirileri onaylayabilir, kısmi çevirileri nasıl ele alırsınız ve hangi çevirilerin güncel olmadığı nasıl takip edilir. Kaynak dilden geride kalan çevirilerin başında kısa bir not göstermeyi düşünün.
Projeniz sürüm yayıyorsa, kullanıcıların ne okuyacaklarını açıkça belirtin:
Tam doküman versiyonlaması olmasa bile, farkı açıklayan küçük bir banner veya seçici kafa karışıklığını önler.
SSS’leri doküman sisteminde tutun (issue yorumlarının içinde değil). /docs/faq gibi görünür bir yere bağlayın ve insanların hatayla karşılaştıklarında düzeltme yapmaya teşvik edin.
Hızlı kazanımlar davet edin: yazım düzeltmeleri, daha açıklayıcı örnekler, güncel ekran görüntüleri ve “bu benim için işe yaradı” notları. Bunlar yeni katkıcılar için en iyi başlangıç yollarıdır ve sitenizi düzenli olarak iyileştirir.
Eğer yazma ve bakım çalışmasını teşvik etmek istiyorsanız, neyi neden ödüllendirdiğinizi şeffaf hale getirin. Örneğin bazı ekipler küçük sponsorluklar veya krediler sunar; Koder.ai’in platform hakkındaki içerik oluşturma için “kredi kazan” programı ilham verebilir ve hafif, topluluk-dostu ödül sistemleri için uyarlanabilir.
Topluluk odaklı bir site davetkâr olmalı—ama birkaç kişinin sürekli temizlik yapmasının bedelini ödememeli. Amaç, bakım işlerini öngörülebilir, hafif ve paylaşılabilir hale getirmektir.
Herkesin hatırlayabileceği bir ritim seçin ve otomatikleştirebileceğiniz işleri otomatikleştirin.
Bu takvimi /CONTRIBUTING.md içinde belgeleyin; böylece başkaları güvenle adım atabilir.
İçerik anlaşmazlıkları normaldir: ton, isimlendirme, ana sayfaya ne koyulacağı veya bir blog yazısının “resmi” olup olmadığı gibi. Uzun süren tartışmalardan kaçınmak için şunları yazın:
Bu kontrol değil, açıklık içindir.
Takvim karmaşık olmak zorunda değil. Tek bir issue (veya basit bir markdown dosyası) ile yaklaşanları listeleyin:
Bunu blog/haber planlama notlarından bağlayın ki katkıcılar kendileri görev alabilsin.
Tekrarlayan site konularını (yazım hataları, eski ekran görüntüleri, eksik linkler, erişilebilirlik düzeltmeleri) takip edin ve bunları “good first issue” etiketiyle işaretleyin. Kabul kriterlerini açık yazın: “bir sayfayı güncelle + formatlayıcıyı çalıştır + sonucu ekran görüntüle.”
Dokümanlarınıza kısa bir “Yaygın yerel kurulum sorunları” bölümü ekleyin. Örnek:
# clean install
rm -rf node_modules
npm ci
npm run dev
Ayrıca sık görülen 2–3 hatayı (yanlış Node sürümü, eksik Ruby/Python bağımlılığı, port kullanımda) not edin. Bu, geri dönüşleri azaltır ve bakıcı enerjisini korur.
Bir cümlelik bir amaç ifadesi yazın, ardından sitenin gerçekleştirmesi gereken en önemli 1–3 işi listeleyin (örneğin: dokümantasyon, indirmeler, topluluk, güncellemeler). Eğer bir sayfa veya özellik bu işlerden birini desteklemiyorsa, şimdilik non-goal olarak ele alın.
Basit bir kontrol: Sitenin amacını bir cümlede açıklayamıyorsanız, ziyaretçiler de yapamaz.
Ana hedef kitlelerinizi listeleyin ve her birinden beklediğiniz ilk tıklamayı tanımlayın:
Her kitle için gelen ilk 3 soruyu yazın (ör. “Bu proje aktif mi?”, “Hata nerede bildirilir?”) ve navigasyonunuzun bunlara hızlıca cevap verdiğinden emin olun.
İnsanların arama eğilimlerine uyan, kasıtlı olarak ‘sıradan’ bir sitemap ile başlayın:
Yeni içerik bunlardan birine uymuyorsa, bu ya yeni bir içerik türü gerektiğinin (nadir) ya da bilginin repoda daha uygun olduğunun işaretidir.
README geliştirici iş akışları için, web sitesi halka dönük rehberlik için olsun.
README’da tutun:
Web sitesi için:
“Markdown öncelikli” düzenlemeleri ve hızlı yerel önizlemeyi destekleyen bir yığın seçin.
Yaygın seçimler:
Varsayılan yol olarak PR → preview → review → merge hedefleyin.
Pratik adımlar:
Bu, inceleyici-geribildirimi azaltır ve katkıcıların değişikliğin göründüğünden emin olmasını sağlar.
Yapılandırma ve şablonlarla format tartışmalarını azaltın.
Yararlı temel öğeler:
CONTRIBUTING.md dosyanızı “site-öncelikli” ve spesifik yapın.
İçermesi gerekenler:
Kısa tutun ki gerçekten okunsun; gerektiğinde derinlemesine dokümanlara bağlayın.
Bunları sonradan eklenen süslemeler değil, varsayılanlar olarak ele alın:
alt="")Otomatik kontroller (link checker, Markdown lint, formatlama) kullanarak inceleyicilerin elinden alın.
Güncellemeleri kolay ve bakım işlerini öngörülebilir hale getirin.
Topluluk güncellemeleri için:
/docs/faq)/docs/en/..., /docs/es/...Bu ayrım, zamanla içeriğin çakışıp uyumsuzlaşmasını önler.
Bugün ihtiyaçlarınızı karşılayan en basit aracı seçin; ileride gerekebilecek en esnek aracı değil.
/website, /docs, /blog, /.github gibi net yapı/website/README.md ile kopyala-yapıştır komutları/templates klasörü (docs sayfası, öğretici, duyuru)CODEOWNERSAmaç: biri bir yazım hatasını düzeltirken veya yeni bir sayfa eklerken build uzmanı olmamak.
Bakıcı sürdürülebilirliği için:
/privacy gibi bir sayfada ne toplandığını ve nedenini açıklayın