vibeeval/developer-relations

Developer Relations

Open Source Community Management

Community Health Scorecard

| Metrik | Saglikli | Dikkat | Kritik | |--------|---------|--------|--------| | Time to First Response | < 24 saat | 1-3 gun | > 3 gun | | Issue Close Rate (monthly) | > %70 | %40-70 | < %40 | | PR Merge Time | < 3 gun | 3-7 gun | > 7 gun | | External Contributors | > %30 | %10-30 | < %10 | | Bus Factor | > 3 | 2-3 | 1 | | Release Cadence | Regular (2-4 hafta) | Duzensiz | > 3 ay | | Documentation Coverage | > %80 | %50-80 | < %50 |

Community Roles & Responsibilities

Maintainer
  |-- Core Contributor (write access)
  |     |-- Regular Contributor (frequent PRs)
  |     |     |-- Occasional Contributor (1-5 PRs)
  |     |           |-- First-time Contributor
  |-- Reviewer (code review)
  |-- Triage (issue labeling)
  |-- Community Moderator (Discord/Slack)
  |-- Documentation Contributor

Issue Triage Labels

# Issue labels taxonomy
type:
  - bug                    # Something isn't working
  - feature                # New feature request
  - enhancement            # Improvement to existing feature
  - documentation          # Documentation update
  - question               # Community question

priority:
  - critical               # Production breaking
  - high                   # Important, next release
  - medium                 # Normal priority
  - low                    # Nice to have

status:
  - needs-triage           # Awaiting maintainer review
  - confirmed              # Bug confirmed, feature accepted
  - needs-info             # Waiting for reporter input
  - in-progress            # Being worked on
  - blocked                # Dependency blocker

experience:
  - good-first-issue       # Newcomer friendly
  - help-wanted            # Community contribution welcome
  - mentor-available       # Maintainer will guide

Automated Community Workflows

# .github/workflows/community.yml
name: Community Management

on:
  issues:
    types: [opened]
  pull_request:
    types: [opened]

jobs:
  welcome-new-contributor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/first-interaction@v1
        with:
          issue-message: |
            Welcome to the project! Thanks for opening your first issue.
            Please make sure you've filled out the issue template completely.
            A maintainer will review this shortly.
          pr-message: |
            Thanks for your first PR! A maintainer will review it soon.
            Please make sure all checks pass and you've signed the CLA.

  auto-label:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/labeler@v5
        with:
          repo-token: "${{ secrets.GITHUB_TOKEN }}"

  stale-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/stale@v9
        with:
          stale-issue-message: "This issue has been inactive for 30 days. It will be closed in 7 days if no further activity occurs."
          days-before-stale: 30
          days-before-close: 7

Developer Documentation Best Practices

Documentation Architecture

docs/
  getting-started/
    installation.md          # 5 dakikada calistir
    quickstart.md            # Ilk basari deneyimi
    configuration.md         # Temel ayarlar
  guides/
    authentication.md        # How-to guide
    data-migration.md        # Step-by-step
    deployment.md            # Production setup
  reference/
    api/                     # Auto-generated API docs
    cli/                     # CLI commands
    configuration/           # All config options
  concepts/
    architecture.md          # Mimari aciklama
    data-model.md            # Data yapisi
  examples/
    basic/                   # Basit ornekler
    advanced/                # Ileri ornekler
    integrations/            # 3rd party entegrasyonlar
  contributing/
    CONTRIBUTING.md          # Katki rehberi
    CODE_OF_CONDUCT.md       # Davranis kurallari
    DEVELOPMENT.md           # Dev environment setup
  changelog/
    CHANGELOG.md             # Release notes

Documentation Quality Checklist

| Kriter | Aciklama | |--------|----------| | 5-Minute Success | Yeni kullanici 5 dk'da calisan bir sey gorebilmeli | | Copy-Paste Ready | Kod ornekleri direkt calisabilmeli | | Up-to-Date | Kod degisince doc da guncellenecek (CI check) | | Searchable | Arama motoru ile bulunabilir | | Progressive Disclosure | Basit -> Orta -> Ileri siralama | | Error Messages | Hata mesajlari doc'a linklemeli | | Platform Coverage | macOS, Linux, Windows ornekleri | | Language Coverage | En az 3 dilde SDK ornegi |

API Documentation Template

## Create User

Creates a new user account.

### Request

`POST /api/v1/users`

#### Headers

| Header | Required | Description |
|--------|----------|-------------|
| Authorization | Yes | Bearer token |
| Content-Type | Yes | application/json |

#### Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | Valid email address |
| name | string | Yes | Full name (2-100 chars) |
| role | string | No | "admin" or "member" (default: "member") |

#### Example

\```bash
curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "Jane Smith",
    "role": "member"
  }'
\```

### Response

#### 201 Created

\```json
{
  "id": "usr_abc123",
  "email": "[email protected]",
  "name": "Jane Smith",
  "role": "member",
  "created_at": "2026-01-15T10:30:00Z"
}
\```

#### 400 Bad Request

\```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format"
  }
}
\```

#### 409 Conflict

\```json
{
  "error": {
    "code": "DUPLICATE_EMAIL",
    "message": "A user with this email already exists"
  }
}
\```

Tutorial ve Workshop Olusturma

Tutorial Structure

1. WHAT: Ne yapacagiz? (1 paragraf, 30 saniye okuma)
2. WHY: Neden onemli? (1 paragraf)
3. PREREQUISITES: Nelere ihtiyac var? (liste)
4. STEPS: Adim adim (her adim bitmis, calisan bir sey)
   - Step 1: Setup (copy-paste)
   - Step 2: Basic usage (calisan output goster)
   - Step 3: Build something (gercek problem coz)
   - Step 4: Advanced (opsiyonel)
5. NEXT STEPS: Sonra ne yapabilirim? (linkler)
6. TROUBLESHOOTING: Yaygın sorunlar ve cozumleri

Workshop Format (90 Dakika)

00:00 - 00:10  Giris ve motivasyon (demo goster)
00:10 - 00:20  Setup kontrolu (herkes calisiyor mu?)
00:20 - 00:40  Guided exercise 1 (birlikte yapariz)
00:40 - 00:50  Solo exercise 1 (kendiniz yapin)
00:50 - 01:00  Ara + sorular
01:00 - 01:20  Guided exercise 2 (ileri seviye)
01:20 - 01:30  Solo exercise 2
01:30 - 01:40  Showcase (katilimcilar gosterir)
01:40 - 01:50  Q&A + next steps

Conference Talk Preparation

Talk Structure Template

Title: [Catchy, specific, searchable]
Duration: [15/25/40 min]
Audience Level: [Beginner/Intermediate/Advanced]

OUTLINE:
1. Hook (2 min)
   - Surprising stat or demo
   - "How many of you have...?"

2. Problem (3 min)
   - Pain point everyone recognizes
   - Why existing solutions fall short

3. Solution (Main Content) (60% of time)
   - Core concept explanation
   - Live demo or code walkthrough
   - Before/After comparison

4. Deep Dive (20% of time)
   - Technical details
   - Architecture decisions
   - Performance numbers

5. Takeaways (3 min)
   - 3 actionable items
   - Resources & links
   - QR code to slides/repo

Speaker Checklist

| Asama | Kontrol | |-------|---------| | Proposal | CFP'ye uygun mu? Abstract compelling mi? | | Slides | Max 1 nokta per slide, buyuk font (24pt+) | | Demo | Offline calisir mi? Backup video var mi? | | Timing | Prova yapildi mi? %10 buffer biraktin mi? | | Setup | Adaptor, clicker, backup laptop? | | After | Slides paylastin mi? Repo public mi? |

Developer Advocate Programi

Advocate Tipleri

| Tip | Odak | Ciktilar | |-----|------|---------| | Content Advocate | Blog, video, tutorial | Haftalik icerik | | Community Advocate | Forum, Discord, events | Gunluk etkilesim | | Technical Advocate | SDK, samples, integrations | Kod + doc | | Field Advocate | Customer visits, workshops | Aylik workshop | | Product Advocate | Feedback loop, beta testing | Feature requests |

Advocate Program Metrics

interface AdvocateMetrics {
  content: {
    blog_posts: number;
    videos: number;
    tutorials: number;
    total_views: number;
    avg_engagement_rate: number;
  };
  community: {
    questions_answered: number;
    avg_response_time_hours: number;
    community_satisfaction: number;   // 1-5
    new_members_influenced: number;
  };
  events: {
    talks_given: number;
    workshops_run: number;
    attendees_reached: number;
    post_event_signups: number;
  };
  product: {
    feedback_submitted: number;
    features_influenced: number;
    beta_testers_recruited: number;
    sdk_contributions: number;
  };
}

Community Metrics

GitHub Community Health

interface GitHubHealth {
  stars: number;
  star_growth_weekly: number;
  forks: number;
  open_issues: number;
  closed_issues_30d: number;
  open_prs: number;
  merged_prs_30d: number;
  contributors_total: number;
  contributors_new_30d: number;
  avg_issue_close_time_hours: number;
  avg_pr_merge_time_hours: number;
  releases_90d: number;
  commit_frequency_weekly: number;
  code_frequency: { additions: number; deletions: number };
}

// GitHub API ile metrikleri cek
async function fetchGitHubHealth(owner: string, repo: string): Promise<GitHubHealth> {
  const headers = { Authorization: `token ${process.env.GITHUB_TOKEN}` };

  const [repoData, issues, prs, contributors, releases] = await Promise.all([
    fetch(`https://api.github.com/repos/${owner}/${repo}`, { headers }).then(r => r.json()),
    fetch(`https://api.github.com/repos/${owner}/${repo}/issues?state=all&per_page=100`, { headers }).then(r => r.json()),
    fetch(`https://api.github.com/repos/${owner}/${repo}/pulls?state=all&per_page=100`, { headers }).then(r => r.json()),
    fetch(`https://api.github.com/repos/${owner}/${repo}/contributors?per_page=100`, { headers }).then(r => r.json()),
    fetch(`https://api.github.com/repos/${owner}/${repo}/releases?per_page=10`, { headers }).then(r => r.json()),
  ]);

  return {
    stars: repoData.stargazers_count,
    star_growth_weekly: 0, // weekly delta hesapla
    forks: repoData.forks_count,
    open_issues: repoData.open_issues_count,
    closed_issues_30d: issues.filter((i: any) => i.state === "closed").length,
    open_prs: prs.filter((p: any) => p.state === "open").length,
    merged_prs_30d: prs.filter((p: any) => p.merged_at).length,
    contributors_total: contributors.length,
    contributors_new_30d: 0,
    avg_issue_close_time_hours: 0,
    avg_pr_merge_time_hours: 0,
    releases_90d: releases.length,
    commit_frequency_weekly: 0,
    code_frequency: { additions: 0, deletions: 0 },
  };
}

Community Growth Metrics

| Metrik | Tanim | Hedef | |--------|-------|-------| | Stars / Week | Haftalik yeni star | +50/hafta | | Fork-to-Star Ratio | forks / stars | > %10 | | Contributor Growth | Aylik yeni contributor | +5/ay | | Issue Activity | Acilan + kapanan issue | Kapanan > Acilan | | PR External Ratio | external_prs / total_prs | > %30 | | Time to First Response | Ilk yanit suresi | < 24 saat | | Community NPS | Net Promoter Score | > 50 |

Discord/Slack Community Setup

Channel Structure

# Discord / Slack Channel Yapisi
general/
  #announcements         # Sadece admin yazabilir, onemli duyurular
  #introductions         # Yeni uyeler kendini tanitir
  #general-chat          # Serbest sohbet

support/
  #help                  # Teknik sorular
  #bug-reports           # Bug raporlari
  #feature-requests      # Feature istekleri

development/
  #contributing          # Katki rehberi, PR tartismalari
  #architecture          # Tasarim tartismalari
  #releases              # Release duyurulari (webhook)

showcase/
  #show-and-tell         # Topluluk projeleri
  #blog-and-content      # Icerik paylasimi

moderation/
  #mod-log               # Moderasyon kayitlari (sadece mod)
  #reports               # Kural ihlali raporlari

Community Bot Commands

const botCommands = {
  "/help": "Yardim menusu goster",
  "/docs <topic>": "Dokumantasyon linki gonder",
  "/issue <title>": "GitHub issue olustur",
  "/faq": "Sikca sorulan sorular",
  "/status": "Servis durumunu goster",
  "/version": "Son surum bilgisi",
  "/search <query>": "Docs + issues + discussions ara",
  "/feedback <message>": "Anonim geri bildirim gonder",
};

Newsletter ve Blog Stratejisi

Content Calendar Template

| Hafta | Blog | Newsletter | Social | Community | |-------|------|-----------|--------|-----------| | 1 | Tutorial | Monthly digest | Thread | Office hours | | 2 | Case study | - | Tips thread | - | | 3 | Technical deep dive | - | Demo video | Community call | | 4 | Changelog/Release | - | Announce | Feedback survey |

Blog Post Types & Frequency

| Tip | Frekans | Hedef | Uzunluk | |-----|---------|-------|---------| | Tutorial | Haftalik | Yeni kullanicilar | 1500-2500 kelime | | Technical Deep Dive | 2 haftada 1 | Ileri seviye | 2000-3500 kelime | | Case Study | Aylik | Social proof | 1000-1500 kelime | | Release Notes | Her release | Mevcut kullanicilar | 500-1000 kelime | | Opinion / Thought Leadership | Aylik | SEO + authority | 1500-2500 kelime |

Developer Experience (DX) Measurement

DX Scorecard

| Boyut | Metrik | Olcum | |-------|--------|-------| | Time to Hello World | Ilk calisan ornek suresi | < 5 dakika | | Error Message Quality | Hatadan cozume sure | Anket + gozlem | | SDK Ergonomics | API calls per task | Kod analizi | | Documentation Findability | Arama -> cozum suresi | Kullanici testi | | Support Response Time | Ilk yanit suresi | Otomatik olcum | | Breaking Changes | Major version upgrade suresi | Anket |

DX Survey Template

1. Urunumuzu kullanmaya baslamak ne kadar kolay? (1-5)
2. Dokumantasyonumuz ihtiyacinizi ne kadar karsiyor? (1-5)
3. Hata mesajlari problemi cozmekte ne kadar yardimci? (1-5)
4. SDK/API'miz ne kadar sezgisel? (1-5)
5. Destek ekibimizin yanit suresi nasil? (1-5)
6. En buyuk engel nedir? (acik ucu)
7. Bizi baska developer'lara onerir misiniz? (0-10, NPS)

CONTRIBUTING.md Template

# Contributing to [Project Name]

Thank you for your interest in contributing!

## How to Contribute

### Reporting Bugs
- Use the bug report template
- Include reproduction steps
- Include environment details (OS, runtime version)

### Suggesting Features
- Check existing issues first
- Use the feature request template
- Explain the use case, not just the solution

### Pull Requests
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests (`npm test`)
5. Run linting (`npm run lint`)
6. Commit with conventional commits (`feat: add amazing feature`)
7. Push to your fork
8. Open a Pull Request

### Development Setup
\```bash
git clone https://github.com/org/project.git
cd project
npm install
cp .env.example .env
npm run dev
\```

### Coding Standards
- TypeScript strict mode
- ESLint + Prettier formatting
- 80% test coverage minimum
- Conventional commits

### Review Process
1. Automated checks must pass (CI)
2. At least 1 maintainer approval
3. No unresolved comments
4. Squash merge to main

## Code of Conduct
This project follows the [Contributor Covenant](https://www.contributor-covenant.org/).
Be respectful, inclusive, and constructive.

Anti-Patterns

| Anti-Pattern | Dogru Yol | |-------------|-----------| | "Build it and they will come" | Aktif community management yap | | Sadece star sayisina bakmak | Contributor diversity ve engagement olc | | Doc'u bir kere yazip unutmak | CI'da doc freshness check koy | | Tek kanal community | Multi-platform varlik (GitHub + Discord + Twitter) | | Sadece ingilizce | i18n doc + lokal community | | PR'lari haftalarca bekletmek | 72 saat iceinde ilk review | | Negativity'yi ignore etmek | Code of Conduct + aktif moderasyon | | Feedback almamak | Duzeli anket + office hours |