# Documentation Structure Guidelines

## Required Documents

Every system MUST have these files:
- README.md (root) - Project overview, badges, quick links
- README.kr.md (root) - Korean translation
- docs/ARCHITECTURE.md - System architecture overview
- docs/API_REFERENCE.md - Complete API documentation
- docs/FEATURES.md - Feature list and descriptions
- docs/CHANGELOG.md - Version history
- docs/PROJECT_STRUCTURE.md - Codebase organization

## Standard Folder Structure

docs/
├── README.md              # Documentation navigation index
├── ARCHITECTURE.md        # System architecture (required)
├── API_REFERENCE.md       # API documentation (required)
├── FEATURES.md            # Feature documentation (required)
├── CHANGELOG.md           # Change history (required)
├── PROJECT_STRUCTURE.md   # Code organization (required)
├── PRODUCTION_QUALITY.md  # Production readiness (optional)
│
├── advanced/              # Internal implementation details
│   ├── ARCHITECTURE.md    # Detailed architecture
│   ├── MIGRATION.md       # Migration guides
│   └── STRUCTURE.md       # Internal structure
│
├── guides/                # User-facing guides
│   ├── QUICK_START.md     # Getting started (recommended)
│   ├── INTEGRATION.md     # Integration with other systems
│   ├── BEST_PRACTICES.md  # Usage recommendations
│   ├── FAQ.md             # Frequently asked questions
│   └── TROUBLESHOOTING.md # Problem resolution
│
├── performance/           # Performance documentation
│   ├── BASELINE.md        # Performance baselines (required)
│   └── TUNING.md          # Optimization guide
│
├── contributing/          # Contributor guides
│   ├── CONTRIBUTING.md    # How to contribute
│   └── CI_CD_GUIDE.md     # CI/CD setup
│
└── integration/           # System integration docs
    └── README.md          # Integration overview

## Naming Conventions

| Pattern | Usage | Example |
|---------|-------|---------|
| UPPER_CASE.md | Core documents | ARCHITECTURE.md |
| lower_case.md | Guides and tutorials | quick_start.md |
| .kr.md suffix | Korean translations | README.kr.md |
| _KO.md suffix | (deprecated) | Do not use |

## Translation Requirements

- All required documents should have Korean translations
- Korean files use `.kr.md` suffix (not `_KO.md`)
- Place translations alongside originals
- Keep translations in sync with English versions

## Document Templates

### Architecture Document
- Overview section with diagram
- Component descriptions
- Data flow explanation
- Design decisions rationale

### API Reference
- Public interfaces/classes
- Method signatures with descriptions
- Usage examples
- Error handling

### Feature Document
- Feature list with descriptions
- Use cases
- Configuration options
- Performance characteristics