📘 Saga Documentation Style Guide¶

Этот guide определяет единый стиль и конвенции для всей документации проекта Saga.

Общие принципы¶

Ключевые ценности¶

Clarity over Cleverness - понятность важнее красивости
Consistency over Personal Style - следуй конвенциям, не изобретай свой стиль
Practicality over Completeness - практичные примеры важнее полного coverage
Accuracy over Speed - лучше медленно но точно

Целевой читатель¶

Помни для кого пишешь:

User docs → человек который хочет инвестировать, не технический background
Business docs → PM/stakeholder который принимает решения
Developer docs → разработчик который интегрирует или contributes
DeFi docs → blockchain expert с глубоким техническим знанием

🗣️ Tone & Voice по аудиториям¶

👥 User Documentation¶

Tone: Дружелюбный, простой, помогающий

DO:

✅ Используйте простые слова: "перевести деньги" вместо "инициировать транзакцию"
✅ Объясняйте термины: "Стейкинг - это когда вы..."
✅ Будьте encouraging: "Это просто! Вот как..."
✅ Предупреждайте о рисках ясно и честно

DON'T:

❌ Не используйте технический жаргон без объяснений
❌ Не предполагайте знание DeFi/crypto
❌ Не пишите в passive voice
❌ Не пугайте сложностью

Примеры:

# ПРАВИЛЬНО
Чтобы начать инвестировать, подключите ваш MetaMask кошелёк.
Это займёт всего минуту!

# НЕПРАВИЛЬНО
Для аутентификации требуется инициализация Web3 provider
через метод wallet connection interface.

💼 Business Documentation¶

Tone: Профессиональный, стратегический, высокоуровневый

DO:

✅ Фокус на value proposition и business outcomes
✅ Используйте metrics и numbers
✅ Структурируйте executive summaries
✅ Highlight competitive advantages

DON'T:

❌ Не углубляйтесь в технические детали implementation
❌ Не используйте code examples
❌ Не предполагайте technical context

Примеры:

# ПРАВИЛЬНО
Saga обеспечивает 15% снижение operational overhead через
автоматизацию custody operations, что позволяет операторам
фокусироваться на strategy вместо infrastructure.

# НЕПРАВИЛЬНО
Наш custody provider интегрируется через REST API с
authentication middleware который использует JWT tokens...

👨‍💻 Developer Documentation¶

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

DO:

✅ Будьте конкретны: "Run make restart" не "restart the system"
✅ Добавляйте working code examples
✅ Объясняйте "why" не только "how"
✅ Link к related technical docs

DON'T:

❌ Не пропускайте error cases
❌ Не предполагайте знание internal architecture
❌ Не пишите "obviously" или "simply"

Примеры:

# ПРАВИЛЬНО
```go
// ValidateEmail проверяет формат email через regex
result := canonical.ValidateEmail(email)
if !result.IsValid {
    return result.Error  // "Invalid email format"
}

НЕПРАВИЛЬНО¶

Просто валидируйте email. Это очевидно как делать.

### DeFi Specialist Documentation

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

**DO:**

- ✅ Используйте правильную DeFi терминологию
- ✅ Детально объясняйте protocol mechanics
- ✅ Highlight security considerations
- ✅ Provide math/формулы когда applicable

**DON'T:**

- ❌ Не упрощайте сложные концепции
- ❌ Не пропускайте edge cases
- ❌ Не игнорируйте security implications

**Примеры:**

```markdown
# ПРАВИЛЬНО
Exchange rate updates используют compound interest formula:
`dailyRate = (1 + APY)^(1/365) - 1`

Для 5% APY: dailyRate ≈ 0.000133737 (0.0133737%)

Security consideration: Owner-only `_authorizeUpgrade()`
предотвращает unauthorized proxy upgrades.

# НЕПРАВИЛЬНО
Стейкинг просто увеличивает ваши токены каждый день.

Language Guidelines¶

Русский vs English¶

Общее правило: Документация пишется преимущественно на русском с английскими терминами где это естественно.

Английские термины (НЕ переводим):

Technical terms: API, endpoint, JWT, transaction, staking
Code concepts: function, service, repository, handler
DeFi terms: yield, APY, liquidity, vault
Proper names: MetaMask, Docker, PostgreSQL

Русские термины (переводим):

Business concepts: стратегия, доход, риск, клиент
User actions: перевод, депозит, вывод средств
General words: руководство, пример, настройка

Примеры natural mixing:

# ПРАВИЛЬНО
Для аутентификации используйте JWT токен, полученный через
endpoint `/api/auth/wallet/authenticate`.

Стратегия инвестирования с 10% APY обеспечивает стабильный yield.

# НЕПРАВИЛЬНО (слишком много англицизмов)
Для authentication используйте JWT token, received через
endpoint `/api/auth/wallet/authenticate`.

# НЕПРАВИЛЬНО (неестественный перевод)
Для удостоверения личности используйте жетон веб-токена JSON...

Commands и Code¶

Всегда на английском:

Команды: make restart, npm install
Переменные: JWT_SECRET, API_KEY
Function names: ValidateEmail(), GetUserBalance()
File paths: backend/shared/services/canonical/user_service.go

Комментарии к коду:

Code comments: на английском
Описания в документации: на русском
NatSpec в Solidity: на английском

# ПРАВИЛЬНО
Запустите команду для перезапуска системы:
```bash
make restart  # Restart with rebuild if needed

НЕПРАВИЛЬНО¶

Запустите команду для перезапуска системы:

сделать перезапуск

---

## Markdown Formatting

### Заголовки

**Hierarchy:**

```markdown
# H1 - Title документа (только один)
## H2 - Основные секции
### H3 - Подсекции
#### H4 - Детали (используйте умеренно)
##### H5 - Избегайте (слишком глубокая вложенность)

Conventions:

Используйте sentence case: "API documentation" не "API Documentation"
Пустая строка до и после заголовка
Не используйте trailing punctuation в заголовках

# ПРАВИЛЬНО
## API authentication

Content here...

## Error handling

# НЕПРАВИЛЬНО
##API Authentication.
Content immediately...
## Error Handling!

Списки¶

Ordered lists (когда порядок важен):

1. First step
2. Second step
3. Third step

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

- Feature A
- Feature B
- Feature C

Task lists (для TODOs):

- [x] Completed task
- [ ] Pending task

Nested lists:

- Parent item
  - Child item (2 spaces indent)
    - Grandchild item (4 spaces indent)

Code Blocks¶

С указанием языка:

```go
func ValidateEmail(email string) bool {
    return emailRegex.MatchString(email)
}
```

```typescript
const validateEmail = (email: string): boolean => {
    return emailRegex.test(email);
}
```

```bash
make restart
make test
```

Inline code:

Используйте функцию `ValidateEmail()` для проверки email.
Переменная `JWT_SECRET` должна быть установлена в `.env` файле.

Links¶

Внутренние (relative paths):

[Link text](./path/to/document.md)
[Section link](./document.md#section-name)
[Parent directory](../other-category/document.md)

Внешние (absolute URLs):

[External link](https://example.com)
[Documentation](https://docs.example.com/guide)

Reference-style links (для множественных ссылок):

Check [API docs][api] and [Architecture guide][arch].

[api]: ./developers/api/README.md
[arch]: ./architecture/overview.md

Tables¶

Standard format:

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Row 1    | Data     | Value    |
| Row 2    | Data     | Value    |

Alignment:

| Left align | Center align | Right align |
|:-----------|:------------:|------------:|
| Text       | Text         | Number      |

Emphasis¶

Bold для important terms:

**Important concept** или **ключевой термин**

Italic для emphasis:

*This is emphasized* или *это подчёркнуто*

Bold + Italic (редко):

***Критически важно***

Code для technical terms:

Используйте `make restart` для перезапуска

Blockquotes¶

Для notes и warnings:

> 💡 **Tip:** Это полезная подсказка

> ⚠️ **Warning:** Это важное предупреждение

> 🔥 **Critical:** Критически важная информация

Horizontal Rules¶

Для разделения секций:

---

New section starts here

Emojis¶

Используйте умеренно для улучшения readability:

Допустимые emojis:

✅ Success, correct
❌ Error, incorrect
⚠️ Warning
💡 Tip, idea
🔥 Important, critical
📋 Note, list
🚀 Action, deployment
🔐 Security
📊 Data, analytics
🎯 Goal, target

Не используйте:

Decorative emojis без значения
Множественные emojis подряд
Emojis в place of words

# ПРАВИЛЬНО
✅ This feature is implemented
⚠️ **Warning:** Backup your data first

# НЕПРАВИЛЬНО
🎉🎉🎉 This is so cool!!! 🚀🚀🚀
Let's 🔥 deploy 🚀 this 💯 code ✨

💻 Code Examples Standards¶

Общие требования¶

Каждый code example должен быть:

Runnable - работает as-is без modifications
Commented - объясняет key parts
Tested - проверен перед добавлением в docs
Minimal - только необходимый код

Go Examples¶

// ✅ ПРАВИЛЬНО: Complete, runnable, commented
func ExampleValidateEmail() {
    // Validate user email address
    result := canonical.ValidateEmail("user@example.com")

    if !result.IsValid {
        log.Printf("Validation failed: %s", result.Error)
        return
    }

    log.Println("Email is valid")
}

// ❌ НЕПРАВИЛЬНО: Incomplete, no context
func ValidateEmail() {
    canonical.ValidateEmail(email)
}

TypeScript/JavaScript Examples¶

// ✅ ПРАВИЛЬНО: Typed, complete, with error handling
async function connectWallet(): Promise<Address> {
    try {
        const address = await connector.connect();
        console.log('Wallet connected:', address);
        return address;
    } catch (error) {
        console.error('Connection failed:', error);
        throw error;
    }
}

// ❌ НЕПРАВИЛЬНО: No types, no error handling
async function connectWallet() {
    return await connector.connect();
}

Bash/Shell Commands¶

# ПРАВИЛЬНО: With description and expected output
make restart              # Restart system with rebuild
# Output: ✅ Container restarted successfully

make test                 # Run foundation tests (~5 min)
# Output: ✅ 118 tests passed

# НЕПРАВИЛЬНО: No context or expected result
make restart
make test

cURL Examples¶

# ПРАВИЛЬНО: Complete with headers and formatted response
curl -X POST http://localhost:8080/api/auth/wallet/authenticate \
  -H "Content-Type: application/json" \
  -d '{
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "signature": "0x..."
  }'

# Response:
# {
# "token": "eyJhbGciOiJIUzI1NiIs...",
# "user": { "id": "123", "email": "user@example.com" }
# }

# НЕПРАВИЛЬНО: Incomplete, no response example
curl http://localhost:8080/api/auth/wallet/authenticate

Solidity Examples¶

// ✅ ПРАВИЛЬНО: NatSpec comments, clear logic
/**
 * @dev Stake USDC tokens to receive stUSDC
 * @param amount Amount of USDC to stake (6 decimals)
 * @return stTokensReceived Amount of stTokens received (18 decimals)
 */
function stake(uint256 amount) external returns (uint256 stTokensReceived) {
    require(amount > 0, "Amount must be positive");

    // Transfer USDC from user
    USDC.transferFrom(msg.sender, address(this), amount);

    // Calculate stTokens based on current exchange rate
    stTokensReceived = (amount * PRECISION) / exchangeRate;

    // Mint stTokens to user
    stToken.mint(msg.sender, stTokensReceived);

    emit Staked(msg.sender, amount, stTokensReceived);
}

// ❌ НЕПРАВИЛЬНО: No comments, unclear logic
function stake(uint256 a) external returns (uint256) {
    USDC.transferFrom(msg.sender, address(this), a);
    uint256 r = (a * PRECISION) / exchangeRate;
    stToken.mint(msg.sender, r);
    return r;
}

Terminology & Glossary¶

Saga-Specific Terms¶

Используйте эти термины consistently:

Term	Definition	Context
Banking Window	Концепция Saga как интерфейса между клиентом и оператором	Business, User
Operator	Финансовый оператор управляющий капиталом	Business
Strategy	Investment strategy (5%, 10%, 20% APY)	All
stUSDC	Staking token (stUSDC5, stUSDC10, stUSDC20)	DeFi, Developer
Exchange Rate	Соотношение stUSDC к USDC	DeFi
VPS Node	Production blockchain node (188.42.218.164:8545)	Developer, DeFi
Blue-Green Deployment	Zero-downtime deployment strategy	Developer

DeFi Standard Terms¶

Не изобретайте свои термины:

APY (Annual Percentage Yield) - НЕ "годовая доходность"
Yield - НЕ "прибыль" или "доход"
Staking - НЕ "вложение"
Liquidity - можно "ликвидность"
Smart Contract - можно "смарт-контракт"
Gas - НЕ переводим

Technical Terms¶

Standard terms (НЕ изобретайте новые):

Endpoint - НЕ "точка входа"
Repository - НЕ "хранилище" в контексте кода
Handler - НЕ "обработчик" когда это Go handler
Middleware - НЕ переводим
Service - можно "сервис"

Common Mistakes to Avoid¶

1. Inconsistent Terminology¶

# НЕПРАВИЛЬНО
Используйте wallet address для аутентификации.
Адрес кошелька нужен для регистрации.
Введите адрес вашего бумажника.

# ПРАВИЛЬНО (consistent)
Используйте wallet address для аутентификации.
Wallet address нужен для регистрации.
Введите ваш wallet address.

2. Assuming Knowledge¶

# НЕПРАВИЛЬНО
Obviously, you should use UUPS proxy pattern.

# ПРАВИЛЬНО
Use UUPS proxy pattern for upgradeable contracts.
See [Upgradeable Architecture](../defi-specialists/smart-contracts/upgradeable-architecture.md)
for details.

3. Vague Instructions¶

# НЕПРАВИЛЬНО
Перезапустите систему.

# ПРАВИЛЬНО
Перезапустите Docker контейнер:
```bash
make restart              # Takes ~30 seconds

### 4. Missing Error Cases

```markdown
# НЕПРАВИЛЬНО
```go
user := service.GetUser(id)
fmt.Println(user.Email)

ПРАВИЛЬНО¶

user, err := service.GetUser(id)
if err != nil {
    return fmt.Errorf("failed to get user: %w", err)
}
fmt.Println(user.Email)

### 5. Broken Links

```markdown
# НЕПРАВИЛЬНО
See [API docs](api.md)  # Relative path неправильный

# ПРАВИЛЬНО
See [API docs](./developers/api/README.md)  # Корректный relative path

6. Orphan Documents¶

# НЕПРАВИЛЬНО: Document без ссылок from/to других docs

# ПРАВИЛЬНО: Link в README и related docs в конце:

---

## Related Documentation

- [Architecture Overview](../../architecture/overview.md)
- [API Reference](../api/README.md)
- [Smart Contracts](../../defi-specialists/smart-contracts/overview.md)

Document Structure Template¶

Каждый документ должен следовать этой структуре:

```markdown

Document Title¶

Audience: [user|business|developer|defi-specialist] Brief description (1-2 sentences) of what this document covers.

Overview¶

High-level introduction...

Main Sections¶

Section 1¶

Content...

Section 2¶

Content...

Examples¶

Practical examples...

Common Issues¶

Troubleshooting...

Quick Reference¶

Writing Checklist¶

Before submitting documentation:

Formatting Checklist¶

H1 только для title
Пустые строки вокруг headers
Code blocks с language specification
Tables форматированы правильно
Lists используют правильный type
Emojis использованы умеренно

📞 Questions?¶

Если сомневаетесь в стиле:

Проверьте existing docs как примеры
Обратитесь к Contributing Guide
Ask in team chat
When in doubt, favor clarity

Remember: Consistency > Personal Preference

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

Версия: 2.4.82

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

Статус: Published

📘 Saga Documentation Style Guide¶

Общие принципы¶

Ключевые ценности¶

Целевой читатель¶

🗣️ Tone & Voice по аудиториям¶

👥 User Documentation¶

💼 Business Documentation¶

👨‍💻 Developer Documentation¶

НЕПРАВИЛЬНО¶

Language Guidelines¶

Русский vs English¶

Commands и Code¶

НЕПРАВИЛЬНО¶

Списки¶

Code Blocks¶

Links¶

Tables¶

Emphasis¶

Blockquotes¶

Horizontal Rules¶

Emojis¶

💻 Code Examples Standards¶

Общие требования¶

Go Examples¶

TypeScript/JavaScript Examples¶

Bash/Shell Commands¶

cURL Examples¶

Solidity Examples¶

Terminology & Glossary¶

Saga-Specific Terms¶

DeFi Standard Terms¶

Technical Terms¶

Common Mistakes to Avoid¶

1. Inconsistent Terminology¶

2. Assuming Knowledge¶

3. Vague Instructions¶

ПРАВИЛЬНО¶

6. Orphan Documents¶

Document Structure Template¶

Document Title¶

Overview¶

Main Sections¶

Section 1¶

Section 2¶

Examples¶

Common Issues¶

Related Documentation¶

Quick Reference¶

Writing Checklist¶

Formatting Checklist¶

📞 Questions?¶

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