Thanks to visit codestin.com
Credit goes to github.com

Skip to content

DOC_STANDARDS.md

Latest commit

 

History

History
198 lines (146 loc) · 8.5 KB

DOC_STANDARDS.md

File metadata and controls

198 lines (146 loc) · 8.5 KB

Стандарты структуры документации

Единые стандарты для всех типов README файлов в monorepo

📋 Обязательные секции по типам

1. 🏠 Root README.md

Назначение: Обзор всего monorepo, quick start, навигация

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

  1. # {Project Name} — заголовок с названием проекта
  2. Badges (CI, License, npm version)
  3. Краткое описание проекта (2-3 предложения)
  4. ## 📦 Packages — таблица пакетов с описанием
  5. ## 🏗️ Architecture — краткая схема зависимостей
  6. ## 🚀 Quick Start — установка и использование
  7. ## 🛠️ Development — команды workspace
  8. ## 📖 Documentation — ссылки на документы
  9. ## 🧪 Testing — запуск тестов
  10. ## 🔍 Code Quality — lint, typecheck
  11. ## 🤝 Contributing — ссылка на CONTRIBUTING.md
  12. ## 📄 License

Лимит: Без жесткого лимита (обычно 250-400 строк)

2. 📦 Framework Package README.md

Назначение: API документация для внешних разработчиков

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

  1. # @{scope}/{package-name} — заголовок с npm именем
  2. Краткое описание (1-2 предложения)
  3. Badges (npm version, License)
  4. ## 🎯 Purpose — назначение и принципы
  5. ## 📦 Installation — npm install инструкция
  6. ## 📁 Structure — дерево структуры пакета
  7. ## 🔧 Components — основные компоненты с примерами
  8. ## 🚨 Critical Rules — важнейшие правила
  9. ## 📖 API Reference — список экспортов
  10. ## 🧪 Testing — запуск тестов
  11. ## 🤝 Contributing — ссылка
  12. ## 📄 License
  13. ## 🔗 Links — monorepo root, architecture

Лимит: ≤600 строк (целевое ~500)

3. 🚀 Application Package README.md

Назначение: Пользовательская документация + dev docs

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

  1. # {Application Name} — заголовок
  2. Badges + краткое описание
  3. ## 🎯 Преимущества — отличия от аналогов
  4. ## 📦 Установка — способы установки
  5. ## 🔑 Получение токенов/ключей — если применимо
  6. ## 💬 Примеры использования — реальные сценарии
  7. ## 📚 Покрытие API/Features — таблица возможностей
  8. ## ⚙️ Настройка — параметры конфигурации
  9. ## 🛠️ Устранение проблем — частые проблемы
  10. ## 🔒 Безопасность
  11. ## 🚀 Для разработчиков — архитектура, команды
  12. ## 📖 Документация — ссылки на CLAUDE.md, modules
  13. ## 📄 Совместимость
  14. ## 📝 Лицензия

Лимит: ≤600 строк (целевое ~500)

4. 🔧 Module README.md

Назначение: Конвенции разработки для конкретного модуля

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

  1. # {Module Name} — Конвенции разработки — заголовок
  2. Предупреждение: "Перед {действием} ОБЯЗАТЕЛЬНО прочитай этот файл"
  3. ## 🎯 Назначение {Module} — роль модуля
  4. ## 📁 Структура — дерево модуля
  5. ## 🏗️ {Ключевые концепции} — базовые классы, паттерны
  6. ## 📋 Чек-лист {создания/добавления} — пошаговая инструкция
  7. ## 🚨 Критические правила — требования с примерами ✅/❌
  8. ## 📚 Примеры — ссылки на эталонные реализации
  9. ## 🔗 См. также — ссылки на связанные модули

Лимит: ≤600 строк (целевое ~500)

5. 🧪 tests/README.md

Назначение: Архитектура тестирования

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

  1. # Архитектура тестирования — заголовок
  2. Краткое описание подхода
  3. ## 📁 Структура тестов — дерево tests/
  4. ## 🎯 Типы тестов — Unit, Integration, E2E, Workflow
  5. ## 🔧 Helpers для тестов — mock factories, test clients
  6. ## ✅ Принципы написания тестов — best practices
  7. ## 🚀 Запуск тестов — команды
  8. ## 📊 Coverage — требования
  9. ## 🔒 Изоляция тестов — правила параллельного выполнения
  10. ## 🔍 CI/CD
  11. ## 🎨 Mocking Best Practices
  12. ## 🔌 DI Testing Patterns
  13. ## 📚 Дополнительные материалы

Лимит: ≤500 строк (целевое ~400)

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

1. Единообразие

Все README одного типа имеют одинаковую структуру секций в одинаковом порядке.

2. Целевая аудитория

Каждый README знает свою аудиторию:

  • Root → все (пользователи + разработчики)
  • Framework Package → внешние разработчики (npm пользователи)
  • App Package → конечные пользователи + разработчики
  • Module → разработчики проекта + ИИ агенты
  • tests/ → разработчики проекта

3. Навигация

Каждый README содержит ссылки на связанные документы.

4. Практичность

Чек-листы, примеры ✅/❌, не теория.

5. Cohesion

Документация рядом с кодом, который описывает.

📏 Лимиты размера

Тип README Лимит Целевое Проверка
Root Нет 250-400 Опционально
Framework Package ≤600 ~500 npm run validate:docs
App Package ≤600 ~500 npm run validate:docs
Module ≤600 ~500 npm run validate:docs
tests/ ≤500 ~400 npm run validate:docs

Исключение: Допустимо превышение на 10% при наличии комментария:

<!-- LIMIT_EXCEPTION: причина -->

✅ Проверка соответствия

Автоматическая валидация

# Проверка размеров
npm run validate:docs

# Полная проверка (включая размеры)
npm run validate

Ручная проверка

Чек-лист для ревью README:

  • Присутствуют все обязательные секции для данного типа
  • Секции идут в правильном порядке
  • Заголовок соответствует формату для данного типа
  • Есть ссылки на связанные документы
  • Размер не превышает лимит (или есть LIMIT_EXCEPTION)
  • Используются эмодзи для секций (🎯, 📦, 🚀, etc.)
  • Примеры кода >10 строк вынесены в отдельные файлы
  • Нет дублирования информации из других файлов

🔧 Шаблоны

Детальные шаблоны для каждого типа см. выше в разделе "Обязательные секции по типам".

📚 См. также