📚

Claude Code Rehberi

Dokümantasyon

Geliştirici dokümanları, API referansları (Docusaurus, Astro).

Orta 2-4 günÖrnek: Open source, API docs, kurs

Dokümantasyon = geliştirici ürününüzün kullanım kılavuzu. İyi docs = adopt rate × 3. Stripe, Linear, Vercel — neden seviliyorlar? Docs harika. Modern docs: arama (Algolia), versiyonlama, çoklu dil, kod örnekleri (canlı), API reference, interactive playground. Docusaurus, Nextra veya Astro Starlight ile 2-4 günde yayında.

Kim İçin Uygun?

Open source proje sahipleri
API/SDK satıcıları
Kurum içi internal tool docs
Online kurs eğitmenleri (referans materyal)

Tipik Özellikler

Dokümantasyon için olmazsa olmazlar

Hierarchical sidebar nav

Bölüm + alt sayfa yapısı. Auto-expand current section.

Search (Algolia DocSearch)

Hızlı, global arama. Open source projeler ücretsiz.

Versiyonlama

v1, v2, v3 docs. Eski versiyonlar erişilebilir.

Kod örnekleri (live)

Syntax highlight + copy butonu + interactive (sandpack).

Dark mode

Developer hep dark mode kullanır. Zorunlu.

API reference

OpenAPI/Swagger entegrasyonu — endpoint, params, response.

Çoklu dil (i18n)

Build-time i18n. Önce EN, sonra TR, ES.

MDX ile zengin içerik

Component'ler, tabs, accordion, callout box.

Önerilen Yığın

Astro Starlight veya Docusaurus Algolia DocSearch MDX Sandpack (live code) Mermaid (diagram) Vercel veya Netlify

Adım Adım Kurulum

8 adımda yayında

Framework seçimi (10 dk)

Starlight (Astro, modern, hızlı), Docusaurus (React, en yaygın), Nextra (Next.js, MDX-native). Yeni proje: Starlight tavsiye.

Yapı planı (30 dk)

Başlangıç + Quickstart + Concepts + Guides + API Reference + FAQ. Her kategoride 3-5 sayfa. URL şeması: /docs/[category]/[slug].

Claude Code başlat (60 dk)

'Astro Starlight ile docs sitesi kur. Tailwind. Sidebar, search, dark mode. Algolia DocSearch entegrasyonu.'

$ npm create astro@latest -- --template starlight

İlk 10 sayfa yaz (120 dk)

Quickstart önce: '5 dakikada başla'. Sonra concepts: nasıl çalışıyor. Code örneklerini test et — gerçekten çalışıyor mu?

API reference (60 dk)

OpenAPI spec'iniz varsa otomatik — redoc veya scalar. Yoksa Claude'a: 'Şu API endpoint'leri için referans sayfası yaz.'

Live code playground (60 dk)

Sandpack ile MDX içinde çalışan kod editörü. Kullanıcı kodla oynar, anında sonuç görür.

Search + analytics (30 dk)

Algolia DocSearch başvurusu (ücretsiz). Plausible analytics. Hangi sayfalar çok aranıyor → eksik docs.

Deploy + custom domain (30 dk)

docs.yourcompany.com subdomain. Vercel + CNAME. Otomatik build on git push.

Önemli · Video Slider Rehberi

Dokümantasyon'da Video / Slider Nasıl Yapılır?

Docs'ta video tutorial'lar = ilk başarı %2x. Karmaşık konseptler (auth flow, websocket, OAuth) yazıyla 1500 kelime, videoyla 3 dakika. Quickstart sayfasında video + yanında kod = ideal.

Quickstart sayfasında video

Sayfanın üstüne video yerleştir: 'Ürünü 5 dakikada kur ve ilk çağrıyı yap'. Loom embed yeterli.

import { LiteYouTubeEmbed } from 'astro-embed';

<LiteYouTubeEmbed
  id="QUICKSTART_VIDEO_ID"
  title="5 dakikada başla"
/>

Tabbed: video + kod yan yana

Bir konsept anlatımı: tab 1 video, tab 2 yazılı, tab 3 kod. Kullanıcı tercih etsin.

import { Tabs, TabItem } from '@astrojs/starlight/components';

<Tabs>
  <TabItem label="📺 Video">
    <iframe src="..." />
  </TabItem>
  <TabItem label="📖 Yazılı">
    Detaylı yazılı anlatım...
  </TabItem>
  <TabItem label="💻 Kod">
    ```ts
    const result = await api.call();
    ```
  </TabItem>
</Tabs>

Mini video kütüphanesi

/docs/videos sayfası: kategorize video tutorial'lar. Her sayfanın ilgili videosu altta linklenir.

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
  {videos.map(v => (
    <a key={v.id} href={`/docs/videos/${v.slug}`} className="group">
      <div className="aspect-video rounded-lg overflow-hidden bg-gray-900">
        <img src={v.thumbnail} className="w-full h-full object-cover group-hover:scale-105 transition" />
      </div>
      <h3 className="mt-2 font-bold">{v.title}</h3>
      <p className="text-sm text-gray-500">{v.duration} · {v.category}</p>
    </a>
  ))}
</div>

Screencast ile feature walkthrough

Karmaşık özellik için ekran kaydı + voice-over. Tarayıcıda Loom kayıt, 60 sn.

<div className="my-6 border rounded-xl overflow-hidden">
  <div className="aspect-video">
    <video
      src="/videos/auth-flow.mp4"
      controls
      poster="/videos/auth-flow-poster.jpg"
    />
  </div>
  <div className="p-4 bg-gray-50">
    <h4 className="font-bold">🎥 Auth flow detaylı anlatım (3 dk)</h4>
    <p className="text-sm text-gray-600 mt-1">OAuth, session token, refresh adımları</p>
  </div>
</div>

Interactive code + video combo

Sol: Sandpack (canlı kod), sağ: kısa açıklayıcı video. Kullanıcı kod oynar, video anlatır.

import { Sandpack } from '@codesandbox/sandpack-react';

<div className="grid md:grid-cols-2 gap-4">
  <div>
    <Sandpack
      template="react"
      files={{ 'App.js': starterCode }}
      options={{ showLineNumbers: true }}
    />
  </div>
  <div>
    <video src="/explanation.mp4" controls className="rounded-lg" />
    <p className="mt-2 text-sm text-gray-600">
      Bu kodu çalıştırmak için 'Run' butonuna basın.
      Detaylar için video.
    </p>
  </div>
</div>

Video transkript + zaman damgaları

SEO için tam transkript + tıklanabilir zaman damgaları (chapters).

<details className="border rounded-lg p-4 my-4">
  <summary className="font-bold cursor-pointer">📝 Video bölümleri + transkript</summary>
  <ul className="mt-4 space-y-2">
    <li>
      <button onClick={() => seekTo(0)} className="text-blue-600 hover:underline">
        [00:00]
      </button> Giriş ve neden bu konu önemli
    </li>
    <li>
      <button onClick={() => seekTo(45)} className="text-blue-600 hover:underline">
        [00:45]
      </button> Auth flow açıklaması
    </li>
    {/* ... */}
  </ul>
  <div className="mt-6 prose">
    {/* Tam transkript */}
  </div>
</details>

Hazır Promptlar

Claude Code'a Yapıştır

Köşeli parantezleri kendi içeriğinizle değiştirin.

Astro Starlight kurulum

Aç ▾

Astro Starlight ile docs sitesi kur:

Komutla başla:
npm create astro@latest -- --template starlight

Yapı:
- /quickstart: 5 dakikada kurulum
- /concepts: nasıl çalışıyor (5 sayfa)
- /guides: how-to'lar (10 sayfa)
- /api: endpoint referansı
- /sdk: SDK kullanımı (her dil için)
- /faq

astro.config.mjs:
- sidebar navigation tanımla
- darkMode default
- searchProvider: 'algolia'
- i18n: 'tr' default, 'en' ek dil
- favicon, logo

Tailwind + Starlight starter content kaldır, kendi içeriğin başla.

API endpoint dokümanı şablonu

Aç ▾

Bir API endpoint için doküman şablonu:

Endpoint: POST /api/users/create

Sayfa içeriği:
1. H1: Create User
2. Description (1 paragraf)
3. Endpoint info: METHOD + URL + auth required
4. Request body (JSON schema, her field açıklamalı)
5. Code examples (tabs):
   - cURL
   - JavaScript fetch
   - Node SDK
   - Python SDK
   - PHP
6. Response examples:
   - Success (200)
   - Validation error (400)
   - Auth error (401)
   - Rate limit (429)
7. Error codes table
8. "Try it" interactive playground
9. Related endpoints

Frontmatter: title, description, tag (auth/users/...).

Migration / changelog sayfası

Aç ▾

Versiyonlama için changelog ve migration guide:

/changelog sayfası:
- v3.0 (2026-01-15)
  - ⚠️ Breaking: ... → migration guide link
  - ✨ New: ...
  - 🐛 Fix: ...
  - 📚 Docs: ...
- v2.x.x ...

/migration/v2-to-v3 sayfası:
1. Niye değişti (rationale)
2. Adım adım nasıl migrate edilir
3. Code diff'leri (önce vs sonra)
4. FAQ
5. Eski API'nin ne zaman deprecate olacağı

RSS feed: /changelog/rss.xml — kullanıcılar takip etsin.

Gerçek Örnek

Bu rehberden gerçek bir vaka

Brief

Open source SDK (TypeScript), GitHub'da 5K star. Docs yetersiz, contributor'lar şikayet ediyor.

Sonuç

3 günde: Starlight ile yenisini kur + 25 sayfa içerik (quickstart, 5 concept, 10 guide, API ref, FAQ). Algolia search, çoklu dil (EN+TR), versiyonlama. docs.project.dev.

Astro StarlightTailwindAlgolia DocSearchMermaidVercel

Sık Hatalar

Bunlardan kaçının

Hata

Quickstart 'önce şunu kurun, sonra şunu, sonra...'

Çözüm

5 dakika kuralı. Eğer 5 dakikada 'hello world' alamıyorsa quickstart başarısız. Test et — yeni kullanıcıya verir, gözlemle.

Hata

Code örneği eski versiyondan

Çözüm

Her release'de docs'u güncelle. CI'da otomatik test: kod örnekleri gerçekten derleniyor mu?

Hata

Tek dil (sadece EN) — Türk geliştirici uzakta

Çözüm

Astro/Docusaurus i18n native. EN önce, sonra TR. Çevirileri AI'la ön taslak, native dilciler düzeltir.

SSS

Dokümantasyon için sık sorular

Starlight, Docusaurus, Nextra — hangisi?▾

2026 için Starlight (Astro) öne çıkıyor — modern, hızlı, küçük build. Docusaurus React, geniş plugin ecosystem. Nextra Next.js'e bağımlıysanız iyi. Yeni proje: Starlight.

Algolia DocSearch nasıl alınır?▾

docsearch.algolia.com'dan başvur. Open source ücretsiz. Onay 1-2 hafta. Alternatif: Pagefind (self-hosted, kurulum 10 dk).

Çoklu versiyon docs nasıl?▾

Docusaurus native versiyonlama destekler. Starlight için ayrı subdomain'ler (v2.docs.x.com, v3.docs.x.com) veya path-based (/v3/docs).