Skip to main content

✍️ Document Style Guide

Bu rehber, ekibimizin bilgi birikimini (Knowledge Base) tutarlı, okunabilir ve sürdürülebilir bir şekilde yönetmemiz için oluşturulmuştur. Rehberin amacı, Döküman özelinde ve docusaurus özelinde rehberlik sağlamaktır. Ancak genel konular (markdown vb.) için Markdown style guide - Google takip ediyoruz. Ayrıca markdown nasıl yazılır bilmiyorsanız buraya bakabilirsiniz.

1. Genel Yazım Prensipleri​

Dil ve Ton​

  • Yalınlık: Karmaşık cümlelerden kaçının. Bir geliştiricinin en hızlı şekilde bilgiye ulaşmasını hedefleyin.
  • Dil: Teknik terimleri orijinal (İngilizce) halleriyle bırakın, ancak açıklamaları Türkçe yapın. (Örn: "Database bağlantı havuzu (connection pool) konfigürasyonu...").
  • Aktif Dil: "Yapılmalıdır" yerine "Yapın" veya "Yapıyoruz" gibi daha net ve aktif ifadeler kullanın.

Görsel Hiyerarşi​

  • Başlıklar: Sadece iki seviye başlık (## ve ###) kullanmaya özen gösterin. Çok derin hiyerarşi okunabilirliği azaltır.
  • Vurgular: Kritik terimleri kalın, dosya isimlerini veya kod parçalarını satır içi kod şeklinde belirtin.
  • Liste Kullanımı: Adım adım işlemler için numaralı listeleri kullanın.

2. Format Spesifik Kurallar​

Genel Döküman Layout​

Genel olarak, yeni bir döküman yazmadan önce aşağıdaki format ile başlayınız:

---
sidebar_position: 1 # (Optional) Hangi konumda gözükmesini istiyorsanız veya konumda değişiklik yapmak istiyorsanız kullanabilirsiniz
slug: /john # (Optional) döküman isminden bağımsız bir adres belirtmek için kullanılır. (docs.teamhalaskar.com/john)
tags: [backend, database, infra] # (Optional) dökümanı ararken kolaylaştırmak için kullanılır. 
---

# Document Title

Short introduction.

[TOC]

## Topic

Content.

## See also

- [link-to-more-info](#)

📜 ADR (Architectural Decision Records)​

Yeni bir mimari karar alınırken mutlaka docs/adr/template.md kullanılmalıdır.

  • Dosya Adı: 000X-kebab-case-baslik.md (Örn: 0004-grpc-migration.md)
  • Zorunlu Alanlar:
    • Context (Bağlam): Karar anındaki durum nedir? Hangi kısıtlar var?
    • Decision (Karar): Net olarak neyi seçtik?
    • Consequences (Sonuçlar): Bu kararın bize maliyeti veya kazancı ne olacak?
  • date metadata kesinlikle eklenmelidir.
  • sidebar_position metadata kesinlikle bulunmamalıdır.

Örnek format aşağıdaki gibidir:

---
title: "ADR-00X: [Kararın Başlığı]"
date: YYYY-MM-DD
status: "Proposed | Accepted | Superseded | Deprecated"
tags: [backend, database, infra]
---

# ADR-00X: [Kararın Başlığı]

- **Tarih:** 202X-XX-XX
- **Durum:** Proposed (Önerildi) / Accepted (Kabul Edildi)
- **Karar Vericiler:** @kullanici1, @kullanici2
- **İlgili Issue/PR (varsa) :** [#123](link)

## 1. Bağlam (Context)
Bu kararı neden almamız gerekiyor? Karşılaştığımız sorun nedir? Mevcut durumdaki kısıtlamalar neler?
> *Örn: Mevcut monolitik yapıdaki DB yükü arttığı için ölçeklendirme sorunu yaşıyoruz.*

## 2. Seçenekler (Alternatives)
Değerlendirilen alternatif çözümler nelerdir?
- **Seçenek A:** [Açıklama]
- **Seçenek B:** [Açıklama]

## 3. Karar (Decision)
Hangi seçeneği, hangi gerekçeyle seçtik?
> *Örn: Seçenek A'yı seçtik çünkü mevcut ekibimiz bu teknolojiye daha hakim ve entegrasyon süresi %30 daha kısa.*

## 4. Sonuçlar (Consequences)
Bu karar neleri değiştirecek? Avantajları ve dezavantajları nelerdir?

### ✅ Artıları (Pros)
- Maddeler halinde...

### ❌ Eksileri (Cons)
- Maddeler halinde...
- Oluşabilecek teknik borçlar veya riskler.

## 5. Notlar ve Referanslar
Varsa makaleler, benchmark sonuçları veya toplantı notları.

👨‍🍳 Cookbook "Tarifleri" (Recipes)​

Bir teknik tarif veya kurulum rehberi yazarken şu akışı izleyin:

  1. Problem: Bu tarif hangi sorunu çözüyor?
  2. Ön Koşullar: Hangi araçlar yüklü olmalı?
  3. Çözüm/Adımlar: Kod blokları ve ekran görüntüleri ile adım adım uygulama.
  4. Doğrulama: İşlemin başarılı olduğunu nasıl anlarız?

3. Docusaurus Özelliklerini Etkili Kullanma​

Uyarı Kutuları (Admonitions)​

Okuyucunun dikkatini dağıtmadan önemli bilgileri vurgulayın:

İpucu

Pratik bir yöntem veya kısayol paylaşırken bunu kullanın.

Bilgi

Genel bilgilendirmeler ve ek kaynaklar için bunu kullanın.

Dikkat

Veri kaybı, güvenlik riski veya geri dönülemez işlemler için mutlaka bunu kullanın.

Kod Blokları​

Her zaman dil belirterek (js, bash, yaml vb.) kod bloğu kullanın ve mümkünse başlık ekleyin:

db-config.js
const dbConfig = { host: 'localhost' };