Шаблоны документации

Стандартизированные шаблоны для написания документации в проекте.

Зачем нужны шаблоны?

Шаблоны обеспечивают:

• Единообразие — вся документация выглядит одинаково
• Полноту — не забудете важные разделы
• Скорость — быстрее создавать новую документацию
• Качество — проверенная структура

Доступные шаблоны

Шаблон интеграции

Для документирования новых интеграций с внешними сервисами:

• Telegram, Instagram, WhatsApp и др.
• Внешние API
• Webhooks

Когда использовать: При добавлении новой интеграции в систему.

---

Шаблон пакета

Для документирования npm-пакетов и библиотек:

• Внутренние пакеты
• Утилиты и хелперы
• Shared libraries

Когда использовать: При создании или документировании npm-пакета.

---

Как использовать шаблон

1. Скопируйте шаблон

cp docs/templates/integration.md docs/integrations/my-integration.md

2. Заполните секции

Замените плейсхолдеры {название}, {описание} и т.д. на актуальные данные.

3. Удалите ненужные секции

Если какая-то секция не применима — удалите её.

4. Добавьте в навигацию

Обновите docs/.vitepress/config.mts для добавления страницы в sidebar.

---

Правила написания документации

Структура документа

1. Заголовок H1 — название
2. Обзор — краткое описание (что это, зачем нужно)
3. Требования — что нужно для работы
4. Установка/Настройка — как начать использовать
5. Использование — примеры кода
6. API Reference — описание методов/эндпоинтов
7. Troubleshooting — частые проблемы
8. Следующие шаги — ссылки на связанные документы

Форматирование

Заголовки

# H1 — Название документа (один на файл)

## H2 — Основные разделы

### H3 — Подразделы

Код

Используйте fence с указанием языка:

```typescript
const example = "code";
```

#### Предупреждения

```markdown
::: tip Совет
Полезная информация
:::

::: warning Внимание
Важное предупреждение
:::

::: danger Опасно
Критическая информация
:::

::: info Информация
Дополнительные сведения
:::

Таблицы

| Колонка 1 | Колонка 2 | Колонка 3 |
| --------- | --------- | --------- |
| Данные    | Данные    | Данные    |

Стиль написания

• Краткость — пишите по делу, без воды
• Практичность — добавляйте примеры кода
• Актуальность — обновляйте при изменениях
• Русский язык — вся документация на русском

Чек-лист перед публикацией

• [ ] Заголовок соответствует содержанию
• [ ] Есть обзор/введение
• [ ] Все примеры кода работают
• [ ] Ссылки ведут на существующие страницы
• [ ] Нет опечаток
• [ ] Добавлено в навигацию (sidebar)

---

Навигация

• Шаблон интеграции
• Шаблон пакета
• Правила кода