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": "user@example.com",
"name": "Jane Smith",
"role": "member"
}'
\```
### Response
#### 201 Created
\```json
{
"id": "usr_abc123",
"email": "user@example.com",
"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 |
