Initial commit: VoIdeaAI - voice-first AI idea assistant

template/docs/10-documentation.md

@@ -0,0 +1,91 @@
+# Стандарты документации
+
+---
+
+## Docstrings
+
+**Формат:** Google-style для всех публичных классов, функций, методов.
+
+```python
+def calculate_roi(investment: float, return_value: float, years: int = 1) -> float:
+    """Calculate Return on Investment.
+
+    Args:
+        investment: Initial investment amount
+        return_value: Total return after period
+        years: Investment period in years (default: 1)
+
+    Returns:
+        ROI as a percentage (e.g., 150.0 for 150%)
+
+    Raises:
+        ValueError: If investment is zero or negative
+    """
+    if investment <= 0:
+        raise ValueError("Investment must be positive")
+    return ((return_value - investment) / investment) * 100
+```
+
+### Когда писать docstrings
+- Всегда для публичных классов и методов
+- Для сложных приватных методов (более 10 строк)
+- Для модулей: краткое описание в начале файла
+
+---
+
+## TODO и FIXME
+
+```python
+# TODO(#TASK-42): Реализовать rate limiting
+# FIXME(#BUG-7): Некорректный подсчёт при пустом списке
+```
+
+---
+
+## README.md
+
+Каждая папка `app/*` должна содержать README.md с кратким описанием:
+- Назначение модуля
+- Ключевые классы/функции
+- Пример использования (если неочевидно)
+
+---
+
+## ADR (Architecture Decision Records)
+
+Каждое архитектурное решение фиксируется в `docs/adr/NNN-title.md`.
+
+ADR нужен когда:
+- Выбирается технология (БД, фреймворк, провайдер)
+- Меняется архитектура (новый слой, новый паттерн)
+- Принимается решение с долгосрочными последствиями
+
+ADR не нужен когда:
+- Обычный багфикс
+- Косметические изменения
+- Выбор имени переменной
+
+---
+
+## CHANGELOG
+
+CHANGELOG — это контракт с пользователем. Каждое изменение, влияющее на работу:
+
+### Для пользователей:
+- Новые функции
+- Изменения API
+- Исправления багов
+- Изменения зависимостей
+
+### Для разработчиков:
+- Рефакторинг (если влияет на API модуля)
+- Изменения конфигурации
+- Обновления БД
+
+---
+
+## [ASK] Вопросы по документации
+
+- Генерировать документацию автоматически? (Sphinx, MkDocs — рекомендуется)
+- Нужна ли API документация для фронтенд-разработчиков? (да, OpenAPI доступен в /docs)
+- Какой формат для диаграмм? (Mermaid — рекомендуется, читается и человеком и ИИ)