swparks-documentation

name	swparks-documentation
description	Правила работы с документацией проекта WorkoutApp

Работа с документацией проекта

Когда применять

• При начале работы с любым функционалом проекта - обязательно изучить соответствующую документацию
• При изменении или доработке существующего функционала - обновить документацию
• При добавлении новых экранов или функций - создать или обновить документацию
• При рефакторинге - проверить актуальность документации и обновить примеры
• При обнаружении несоответствий между документацией и кодом - исправить документацию
• При создании новых документационных файлов в папке docs/

Расположение документации

Основная документация

• Папка docs/ - основная папка с детальной документацией проекта
• README.md - основная информация о проекте, краткое описание функционала и ссылки на детальную документацию

Структура документации в docs/

Документация в папке docs/ пока не создана. При необходимости можно добавить следующие документы:

• feature-map.md - карта экранов и функционала
• setup-guide.md - инструкция по установке и настройке
• deployment.md - инструкции по публикации приложения
• parks.md - документация по экранам площадок
• events.md - документация по экранам мероприятий
• profile.md - документация по экранам профиля
• messages.md - документация по экранам сообщений
• testing-mocks.md - документация по мокам для тестирования

Обязательные правила работы с документацией

При изменении и доработке функционала

1. Изучение документации - обязательно

   • Перед началом работы с любым функционалом обязательно изучи соответствующую документацию в папке docs/ (если она существует)
   • Сверяйся с feature-map.md для понимания текущего состояния экранов и функций (если файл существует)
   • Изучай специфичную документацию (например, parks.md, events.md, profile.md) перед работой с соответствующим функционалом

2. Актуализация документации - обязательно

   • При изменении функционала обязательно обновляй соответствующую документацию (или создавай её, если её нет)
   • Если добавляешь новый экран или функцию - обнови или создай feature-map.md
   • Если изменяешь логику работы - обнови соответствующую специфичную документацию

3. Согласование изменений

   • Перед внесением значительных изменений в основную документацию (README.md, feature-map.md) запрашивай согласование
   • Мелкие актуализации (например, обновление статуса реализации в feature-map.md) можно делать без согласования

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

1. Актуальность

   • Документация должна соответствовать текущему состоянию кода и функционала
   • При обнаружении несоответствий между документацией и кодом - немедленно обновляй документацию
   • Регулярно проверяй актуальность документации при работе с кодом

2. Лаконичность

   • Документация должна быть краткой и по делу
   • Избегай избыточных описаний и повторений
   • Используй структурированный формат (заголовки, списки, таблицы)
   • Удаляй устаревшую информацию при обновлении

3. Понятность

   • Документация должна быть понятной для разработчиков, которые работают с проектом
   • Используй простой и ясный язык
   • Добавляй примеры кода там, где это необходимо
   • Описывай не только "что", но и "почему" в сложных случаях

Контроль качества документации

Регулярные проверки

• При каждом изменении функционала проверяй соответствие документации
• При обнаружении несоответствий исправляй их сразу
• При работе с новым функционалом начинай с изучения документации

Признаки качественной документации

• ✅ Описание соответствует текущему коду
• ✅ Структура понятна и логична
• ✅ Примеры кода актуальны
• ✅ Нет устаревшей информации
• ✅ Документация помогает понять функционал

Заключение

Документация в папке docs/ является важной частью проекта и должна поддерживаться в актуальном состоянии. При любой работе с функционалом необходимо изучать и актуализировать документацию, чтобы она была актуальной, лаконичной и понятной для всех разработчиков проекта.