Dokümantasyon Geliştirme Önerileri

Bu sayfa, kurumsal onboarding hedefiyle mevcut dokümantasyon yapısına eklenmesi veya detaylandırılması önerilen başlıkları öncelik sırasıyla listeler. Her madde uygulandığında yeni katılan developer’ların projeyi daha kısa sürede ve eksiksiz kavraması hedeflenir.

---

1. Yeni Geliştirici Onboarding Sayfası (Öncelik: Yüksek)

Amaç: İlk gün / ilk hafta için net bir yol haritası.

Önerilen içerik:

• İlk gün checklist: Repo klonlama, .dev.vars oluşturma, npm run dev ile uygulamanın ayağa kalkması, ilk sayfa değişikliği (örn. footer metni).
• Okuma sırası: Hangi dokümanların sırayla okunması gerektiği (Giriş → Yerel Kurulum → Ortam Değişkenleri → Proje Yapısı → Route Haritası → İlgili mimari sayfalar).
• İlk değişiklik önerisi: Küçük bir UI değişikliği veya yeni bir link ekleme gibi gerçek bir “ilk PR” senaryosu; hangi dosyalara dokunulacağı, nasıl test edileceği.
• Sorun yaşandığında: Nereye bakılacağı (Ortam Değişkenleri, Geliştirme Akışı, Troubleshooting).

Nereye eklenecek: Yeni sayfa örn. guides/onboarding.mdx; sidebar’da “Giriş ve Başlangıç” altında “Yeni Geliştirici Onboarding” olarak.

---

2. Proje Yapısı (Detaylı) (Öncelik: Yüksek)

Amaç: app/ altındaki her klasörün görevinin ve dosya konvansiyonlarının tek yerde açıklanması.

Önerilen içerik:

• Klasör görevleri: app/routes/, app/components/, app/lib/, app/db/, app/graphql/, app/locales/, app/hooks/ — her birinin ne için kullanıldığı, hangi tür dosyaların nereye konulacağı.
• Route dosya isimlendirmesi: route("path", "routes/dosya.tsx") eşleşmesi; :param → $param, * → catch-all; api.*.ts vs sayfa route’ları.
• Layout hiyerarşisi: $lang.tsx, admin.tsx, instructor.tsx, account.tsx, my-courses.tsx gibi layout route’ların hangi sayfaları sarmaladığı.
• Ortak lib modülleri: lib/auth.ts, lib/db-queries.ts, lib/pricing-engine.ts, lib/graphql-client.ts, lib/video-security.ts vb. kısa açıklamaları.

Nereye eklenecek: Yeni sayfa örn. guides/project-structure.mdx veya mevcut “Geliştirme Akışı”nın hemen altında “Proje Yapısı” başlığı; sidebar’da “Kılavuzlar” altında.

---

3. Route Haritası (Öncelik: Yüksek)

Amaç: Tüm URL’lerin tek tabloda görünmesi; public / auth / öğrenci / eğitmen / admin ayrımı.

Önerilen içerik:

• Tablo: Path (örn. /tr/pricing, /admin/payouts, /api/graphql), Method (GET/POST), Dosya (örn. routes/pricing.tsx), Yetki (public / giriş gerekli / instructor / admin), Kısa açıklama.
• Dil prefix kuralı: Hangi path’lerin /:lang/ altında olduğu, hangi route’ların dil prefix’i olmadığı (api, admin, robots.txt, sitemap.xml, verify/:code).
• API route’ları: Zaten “API Referansı ve GraphQL” sayfasında detay var; Route Haritası’nda sadece path + dosya + kısa açıklama ile özet satır.

Nereye eklenecek: Yeni sayfa örn. reference/route-map.mdx veya guides/route-map.mdx; “Referans” veya “Kılavuzlar” altında “Route Haritası”.

---

4. Kod Konvansiyonları ve Standartlar (Öncelik: Yüksek)

Amaç: Ekip içi tutarlılık; yeni geliştiricinin “nasıl yazmalıyım?” sorusuna yanıt.

Önerilen içerik:

• İsimlendirme: Bileşenler PascalCase, dosyalar kebab-case veya React Router convention; handle* event handler’lar; loader / action export’ları.
• Veri çekme: Sayfa verisi için loader, form / mutation için action; GraphQL ne zaman kullanılır (çoğu sayfa verisi), REST/action ne zaman (upload, webhook, download).
• Yetkilendirme: Session kontrolü nerede yapılır (layout loader); session?.user?.role === "admin" / instructor pattern’i.
• i18n: useTranslation(), t("key"), çeviri dosyalarının yeri (locales/*.json); yeni key ekleme ve fallback.
• Stil: Tailwind kullanımı; class: vs ternary; erişilebilirlik (aria-label, tabindex) kısa hatırlatma.
• TypeScript: context.cloudflare?.env tipi; getDb(env.DATABASE_URL) kullanımı.

Nereye eklenecek: Yeni sayfa örn. guides/code-conventions.mdx; “Kılavuzlar” altında “Kod Konvansiyonları ve Standartlar”.

---

5. Geliştirici Sözlüğü / Terimler (Öncelik: Orta)

Amaç: Projeye özgü terimlerin tek yerde tanımlanması; yabancı dilde gelen developer’lar için de faydalı.

Önerilen içerik:

• Ürün / iş: Enrollment, payout, payout request, tier, price tier, tier_prices, PPP (bölgesel fiyat), affiliate, referral code, Connect (Stripe Connect), manuel ödeme (TR), checkout session, subscription (abonelik), bundle (kurs paketi).
• Teknik: Loader, action, layout route, GraphQL context, signed URL (Bunny), webhook, Hyperdrive, Pull Zone (Bunny).
• Rol: student, instructor, admin; onboarding (eğitmen kaydı sonrası adımlar).

Nereye eklenecek: Yeni sayfa örn. reference/glossary.mdx; “Referans” altında “Sözlük / Terimler”.

---

6. Hata Ayıklama ve Yaygın Sorunlar (Troubleshooting) (Öncelik: Orta)

Amaç: İlk günlerde sık karşılaşılan hatalar ve çözümleri.

Önerilen içerik:

• DB bağlantısı: DATABASE_URL eksik veya yanlış; Hyperdrive yerelde localConnectionString; Neon IP kısıtlaması.
• Stripe webhook: Yerelde stripe listen kullanımı; whsec_... güncellemesi; 401/404 nedenleri.
• Auth: “Giriş yapmanız gerekiyor” — session cookie, BASE_URL / BETTER_AUTH_URL tutarlılığı; OAuth callback URL’i.
• Bunny: Video yüklenmiyor — signed URL için BUNNY_VIDEO_SECURITY_KEY; storage upload için zone/key.
• Build / typecheck: npm run typecheck; React Router typegen; npm run cf-typegen.
• Drizzle migration: drizzle-kit generate / migrate / push ne zaman kullanılır; production’da migration stratejisi.

Nereye eklenecek: Yeni sayfa örn. guides/troubleshooting.mdx; “Kılavuzlar” altında “Hata Ayıklama ve Yaygın Sorunlar”.

---

7. Giriş Sayfası (index) Güncellemesi (Öncelik: Orta)

Amaç: Ana sayfadan “yeni geliştirici” için net bir giriş noktası.

Önerilen eklemeler:

• “Yeni misiniz?” bölümü: “İlk adımlar için Yeni Geliştirici Onboarding ve Yerel Kurulum sayfalarına gidin.”
• Okuma sırası: Kısa numaralı liste (1. Giriş, 2. Kurulum, 3. Ortam, 4. Proje Yapısı, 5. Route Haritası, 6. İlgili mimari).
• Öne çıkan teknik detaylar: Mevcut kartlar kalabilir; isteğe bağlı “API Referansı”, “Route Haritası”, “Sözlük” linkleri eklenebilir.

---

8. Referans Bölümünün Genişletilmesi (Öncelik: Orta)

Mevcut: reference/api-reference.mdx (Platform API Referansı), reference/example.md.

Öneriler:

• Sözlük: Yukarıdaki “Geliştirici Sözlüğü” → reference/glossary.mdx.
• Route haritası: Yukarıdaki “Route Haritası” → reference/route-map.mdx (veya guides’ta).
• Example kılavuzu: reference/example.md / guides/example.md — ya kaldırılır ya da “İlk değişikliği yapmak” gibi gerçek bir senaryoya dönüştürülür (hangi dosya, hangi adımlar, nasıl test).

---

9. Tutarlılık Düzeltmeleri (Öncelik: Düşük)

Amaç: Dokümanlar arası ve README ile uyum.

• Komut tutarlılığı: Projede Bun runtime kullanılmıyor; tüm dokümanlarda npm run dev, npm run start, npx wrangler dev kullanılır.
• Base URL örnekleri: Bazı sayfalarda https://coursio.co, bazılarında https://lms.techsider.co — hangisinin production olduğu tek cümleyle netleştirilebilir.
• Docs vs ana proje: “Bu dokümantasyon sitesi docs/ içinde; ana uygulama kökte” bilgisi Geliştirme Akışı’nda var; Yerel Kurulum’da da kısa hatırlatma eklenebilir.

---

10. Mimari Sayfalarında “İlgili Dosyalar” (Öncelik: Düşük)

Amaç: Her mimari sayfanın sonunda ilgili route/lib dosyalarının listesi.

Öneri: Örneğin “Checkout & Webhooks” sayfasında: app/routes/api.stripe.webhook.ts, app/routes/payment.checkout.tsx, app/lib/stripe-connect-payout.ts gibi. Yeni geliştirici konuyu okuduktan sonra doğrudan hangi dosyaya bakacağını bilir.

---

Özet Tablo

Öneri	Öncelik	Yeni sayfa / Güncelleme	Bölüm
Yeni Geliştirici Onboarding	Yüksek	Yeni: guides/onboarding.mdx	Giriş ve Başlangıç
Proje Yapısı (detaylı)	Yüksek	Yeni: guides/project-structure.mdx	Kılavuzlar
Route Haritası	Yüksek	Yeni: reference/route-map.mdx veya guides	Referans / Kılavuzlar
Kod Konvansiyonları	Yüksek	Yeni: guides/code-conventions.mdx	Kılavuzlar
Geliştirici Sözlüğü	Orta	Yeni: reference/glossary.mdx	Referans
Troubleshooting	Orta	Yeni: guides/troubleshooting.mdx	Kılavuzlar
Giriş sayfası güncellemesi	Orta	Güncelleme: index.mdx	—
Referans genişletme	Orta	Sözlük + Route haritası + Example revizyonu	Referans
Tutarlılık (base URL)	Düşük	README + birkaç doc sayfası	—
Mimari “İlgili dosyalar”	Düşük	Her mimari sayfasına kısa liste	Mimari

---

Bu öneriler uygulandıkça dokümantasyon hem işlevsel (ilk gün checklist, route haritası, troubleshooting) hem de kapsamlı (proje yapısı, konvansiyonlar, sözlük) hale gelir; yeni developer’lar projeye daha kısa sürede adapte olur ve projenin işleyişini daha eksiksiz kavrar.