🤝 Contributing to Saga Documentation¶

Философия документации¶

Документация Saga следует принципам:

Multi-Audience Approach - разные документы для разных ролей
Clarity over Completeness - лучше понятно чем полно
Living Documentation - документация эволюционирует с кодом
Agent-Friendly - структура оптимизирована для AI агентов
Post-Factum Review - создаём сначала, ревьюим потом

Типы документации¶

👥 User Documentation (`docs/user/`)¶

Аудитория: Конечные пользователи платформы

Содержание:

Getting started guides
How-to guides для основных операций
FAQ и troubleshooting
Glossary и educational content

Тон: Простой, дружелюбный, без технических деталей

💼 Business Documentation (`docs/business/`)¶

Аудитория: PM, бизнес-аналитики, дизайнеры, стейкхолдеры

Содержание:

Whitepaper и vision documents
Product roadmap
Competitive analysis
User flows и UX документация
Economic models

Тон: Профессиональный, стратегический, high-level

👨‍💻 Developer Documentation (`docs/developers/`)¶

Аудитория: Backend/frontend разработчики, интеграторы

Содержание:

API Reference
Architecture documentation
Developer guides (setup, testing, deployment)
Code conventions и best practices
Tool documentation

Тон: Технический, точный, с примерами кода

DeFi Specialist Documentation (`docs/defi-specialists/`)¶

Аудитория: Blockchain эксперты, smart contract developers

Содержание:

Smart contract documentation
Protocol specifications
Security documentation
Integration guides для DeFi

Тон: Высокотехнический, детальный, security-focused

Compliance Documentation (`docs/compliance/`)¶

Аудитория: Legal, compliance, regulatory specialists

Содержание:

Regulatory framework
Privacy policy
Terms of service
Risk disclosures

Тон: Юридически точный, формальный

Reference Documentation (`docs/reference/`)¶

Аудитория: Все (справочная информация)

Содержание:

Auto-generated API reference
Config reference
CLI reference (Makefile commands)

Тон: Справочный, структурированный, searchable

Workflow участия¶

1. Найти область для улучшения¶

Автоматически:

make analyze-documentation          # Запустить анализатор
make analyze-documentation-gaps     # Только gaps

Анализатор покажет: - Недокументированные API endpoints - Missing guides - Gaps по аудиториям - Broken links - Outdated documents

Вручную:

Browse документацию и найти неточности
Проверить GitHub issues с тегом documentation
Предложить новые темы

2. Выбрать подходящий шаблон¶

Используйте шаблоны из docs/meta/templates/:

api-endpoint.md - для документирования API endpoint
guide.md - для developer guides
business-doc.md - для бизнес-документов
adr.md - для Architecture Decision Records (уже есть в architecture/decisions/template.md)

3. Написать документ¶

Следуйте Style Guide:

Используйте правильный тон для аудитории
Добавляйте примеры кода где применимо
Структурируйте с помощью заголовков
Добавляйте ссылки на связанные документы

Ключевые принципы:

✅ Конкретность: "Run make restart" вместо "restart the system"
✅ Примеры: Всегда добавляйте практические примеры
✅ Навигация: Ссылки на related docs в конце документа
✅ Актуальность: Указывайте дату последнего обновления

4. Добавить метаданные¶

В начале каждого документа:

# Document Title

**Audience:** [user|business|developer|defi-specialist]
Brief description...

5. Проверить качество¶

Перед submit:

Spell check (русский/английский)
Links работают (внутренние и внешние)
Code examples протестированы
Formatting корректный (markdown validation)
Tone соответствует аудитории

Инструменты:

# Проверка broken links (когда analyzer будет готов)
make analyze-documentation

# Markdown linting (если настроен)
make lint-docs

6. Submit изменения¶

Commit message format:

docs(category): brief description

- Детальное описание изменений
- Почему эти изменения нужны
- Что улучшается

Closes #123  # Если есть связанный issue

Примеры:

docs(api): add authentication endpoint documentation
docs(business): update whitepaper with banking window concept
docs(guides): add deployment troubleshooting section

7. Post-Factum Review¶

После создания документа: - Maintainer проверит accuracy - Возможны комментарии для улучшения - После approval - merge в main

Мы доверяем качеству вашей работы! Review - это collaboration, не barrier.

Best Practices¶

Для всех типов документации¶

DO:

✅ Используйте активный залог ("Run the command" вместо "The command should be run")
✅ Будьте конкретны ("Takes ~2 minutes" вместо "Takes some time")
✅ Добавляйте практические примеры
✅ Ссылайтесь на related docs
✅ Обновляйте "Last Updated" дату

DON'T:

❌ Не дублируйте информацию (ссылайтесь на single source of truth)
❌ Не используйте устаревшие термины
❌ Не пишите "очевидные" вещи без контекста
❌ Не создавайте orphan documents (без ссылок из/к другим docs)

Для кода и команд¶

Всегда форматируйте:

# ПРАВИЛЬНО: С описанием и результатом
make restart              # Перезапуск системы
# Output: ✅ Container restarted successfully

# НЕПРАВИЛЬНО: Без контекста
make restart

Code examples должны быть:

Runnable (работающие как есть)
Commented (с пояснениями)
Tested (проверенные)
Minimal (только необходимый код)

Для API documentation¶

Обязательные секции:

Endpoint: POST /api/endpoint
Description: Что делает endpoint
Authentication: Требования auth
Request: Формат и parameters
Response: Success и error responses
Example: cURL/JavaScript example

Для архитектурных документов¶

Используйте ADR format:

# ADR-NNNN: Title

## Status
[Proposed|Accepted|Deprecated|Superseded]

## Context
Проблема или решение

## Decision
Что решили делать

## Consequences
Последствия решения

Технические детали¶

Markdown Conventions¶

Заголовки:

# H1 - Только для title документа
## H2 - Основные секции
### H3 - Подсекции
#### H4 - Детали (используйте редко)

Списки:

**Ordered (когда порядок важен):**
1. First step
2. Second step

**Unordered (когда порядок не важен):**

- Feature A
- Feature B

**Task lists:**

- [x] Completed
- [ ] Pending

Code blocks:

```language
code here
```

Поддерживаемые языки:
- bash, sh - для команд
- go - для Go кода
- typescript, javascript - для frontend
- solidity - для смарт-контрактов
- json, yaml - для конфигов

Ссылки:

# Внутренние (относительные пути)
[Link text](./relative/path/to/doc.md)
[Section link](./doc.md#section-name)

# Внешние (absolute URLs)
[External link](https://example.com)

# Ссылки на код
See `backend/services/user_service.go:123`

Emojis (опционально для улучшения readability):

✅ Success
❌ Error
⚠️ Warning
💡 Tip
🔥 Important
📋 Note

File Naming¶

Conventions:

Lowercase with hyphens: file-name.md
Descriptive names: authentication-guide.md не auth.md
Category prefixes когда нужно: api-authentication.md

Structure:

docs/
├── category/
│   ├── README.md           # Category overview
│   ├── subcategory/
│   │   ├── README.md       # Subcategory overview
│   │   └── document.md     # Actual document
│   └── another-doc.md

Images и Diagrams¶

Хранение:

docs/
├── images/
│   ├── category/
│   │   └── image-name.png

Usage:

![Alt text](../images/category/image-name.png)

Для диаграмм:

Используйте Mermaid для flowcharts/sequences
PNG для сложных диаграмм
SVG для векторной графики

Priority Areas¶

Текущие gaps (согласно Documentation Implementation Roadmap):

HIGH PRIORITY¶

API Documentation - 102 endpoints требуют документации
Business Docs - Whitepaper, roadmap, economic model
DeFi Protocol Specs - Smart contract documentation

MEDIUM PRIORITY¶

User Documentation - Getting started, FAQ
Integration Guides - Для third-party разработчиков
Security Documentation - Best practices, audit reports

LOW PRIORITY¶

Advanced Guides - Performance tuning, optimization
Historical Documentation - Architecture evolution

Documentation Analyzer¶

После завершения Фазы 6 (Documentation Analyzer), workflow упростится:

# 1. Найти gaps
make analyze-documentation

# 2. Получить agent-friendly TODO
cat logs/analyzers/documentation-gaps.json

# 3. Выбрать priority task
# 4. Создать документ по шаблону
# 5. Submit для post-factum review

Анализатор автоматически: - Находит недокументированные области - Приоритизирует задачи - Генерирует structured TODOs - Валидирует completeness

🤔 FAQ¶

Как узнать что документировать?¶

Запустите make analyze-documentation (когда готов)
Проверьте GitHub issues с тегом documentation
Спросите в team chat
Просто browse docs и находите gaps

Нужно ли согласование перед написанием?¶

Нет! Пишите документ, submit для review. Мы доверяем вашему judgment.

Что если я не уверен в technical details?¶

Сделайте best effort
Пометьте секцию как [TODO: verify]
В PR description укажите где нужна помощь
Reviewer поможет с technical accuracy

Можно ли обновлять существующие docs?¶

Да! Улучшения существующей документации - отличный вклад: - Исправление ошибок - Добавление examples - Улучшение clarity - Обновление outdated info

Как часто обновлять документацию?¶

Когда код меняется:

API changes → update API docs
New features → update relevant guides
Architecture changes → update architecture docs

Regular maintenance:

Quarterly review для outdated docs
After major releases
When analyzer reports gaps

📞 Получить помощь¶

Вопросы по документации:

Create GitHub issue с тегом documentation
Ask in team chat
Проверьте Style Guide
Посмотрите existing docs как примеры

Technical questions:

Для API вопросов → check existing code
Для архитектуры → check ADRs
Для бизнес-контекста → ask PM/stakeholders

Спасибо!¶

Каждый вклад в документацию делает Saga доступнее и понятнее для всех. Ваше участие ценно!

Помните:

📝 Clarity > Perfection
🤝 Collaboration > Competition
🚀 Action > Planning
✅ Progress > Perfection

Happy documenting! 🎊

📋 Метаданные¶

Версия: 2.4.82

Обновлено: 2025-10-21

Статус: Published

🤝 Contributing to Saga Documentation¶

Философия документации¶

Типы документации¶

👥 User Documentation (docs/user/)¶

💼 Business Documentation (docs/business/)¶

👨‍💻 Developer Documentation (docs/developers/)¶

DeFi Specialist Documentation (docs/defi-specialists/)¶

Compliance Documentation (docs/compliance/)¶

Reference Documentation (docs/reference/)¶

Workflow участия¶

1. Найти область для улучшения¶

2. Выбрать подходящий шаблон¶

3. Написать документ¶

4. Добавить метаданные¶

5. Проверить качество¶

6. Submit изменения¶

7. Post-Factum Review¶

Best Practices¶

Для всех типов документации¶

Для кода и команд¶

Для API documentation¶

Для архитектурных документов¶

Технические детали¶

Markdown Conventions¶

File Naming¶

Images и Diagrams¶

Priority Areas¶

HIGH PRIORITY¶

MEDIUM PRIORITY¶

LOW PRIORITY¶

Documentation Analyzer¶

🤔 FAQ¶

Как узнать что документировать?¶

Нужно ли согласование перед написанием?¶

Что если я не уверен в technical details?¶

Можно ли обновлять существующие docs?¶

Как часто обновлять документацию?¶

📞 Получить помощь¶

Спасибо!¶

📋 Метаданные¶

👥 User Documentation (`docs/user/`)¶

💼 Business Documentation (`docs/business/`)¶

👨‍💻 Developer Documentation (`docs/developers/`)¶

DeFi Specialist Documentation (`docs/defi-specialists/`)¶

Compliance Documentation (`docs/compliance/`)¶

Reference Documentation (`docs/reference/`)¶