| 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 - документация по мокам для тестирования
Обязательные правила работы с документацией
При изменении и доработке функционала
-
Изучение документации - обязательно
- Перед началом работы с любым функционалом обязательно изучи соответствующую документацию в папке
docs/ (если она существует)
- Сверяйся с
feature-map.md для понимания текущего состояния экранов и функций (если файл существует)
- Изучай специфичную документацию (например,
parks.md, events.md, profile.md) перед работой с соответствующим функционалом
-
Актуализация документации - обязательно
- При изменении функционала обязательно обновляй соответствующую документацию (или создавай её, если её нет)
- Если добавляешь новый экран или функцию - обнови или создай
feature-map.md
- Если изменяешь логику работы - обнови соответствующую специфичную документацию
-
Согласование изменений
- Перед внесением значительных изменений в основную документацию (README.md, feature-map.md) запрашивай согласование
- Мелкие актуализации (например, обновление статуса реализации в feature-map.md) можно делать без согласования
Принципы качества документации
-
Актуальность
- Документация должна соответствовать текущему состоянию кода и функционала
- При обнаружении несоответствий между документацией и кодом - немедленно обновляй документацию
- Регулярно проверяй актуальность документации при работе с кодом
-
Лаконичность
- Документация должна быть краткой и по делу
- Избегай избыточных описаний и повторений
- Используй структурированный формат (заголовки, списки, таблицы)
- Удаляй устаревшую информацию при обновлении
-
Понятность
- Документация должна быть понятной для разработчиков, которые работают с проектом
- Используй простой и ясный язык
- Добавляй примеры кода там, где это необходимо
- Описывай не только "что", но и "почему" в сложных случаях
Контроль качества документации
Регулярные проверки
- При каждом изменении функционала проверяй соответствие документации
- При обнаружении несоответствий исправляй их сразу
- При работе с новым функционалом начинай с изучения документации
Признаки качественной документации
- ✅ Описание соответствует текущему коду
- ✅ Структура понятна и логична
- ✅ Примеры кода актуальны
- ✅ Нет устаревшей информации
- ✅ Документация помогает понять функционал
Заключение
Документация в папке docs/ является важной частью проекта и должна поддерживаться в актуальном состоянии. При любой работе с функционалом необходимо изучать и актуализировать документацию, чтобы она была актуальной, лаконичной и понятной для всех разработчиков проекта.
