Вы правильно заметили: любая диаграмма быстро устаревает. Как и любая документация. А неактуальные они не только не помогут, но и наврут, и навредят.

Без подробностей о проекте советовать сложно. Но по количеству фронтов предположу, что у вас пока ещё не Гугль. Поэтому советую начать с базы:

Опишите главное коротко, дайте контакты ответственных

Обычно фундаментальные части продукта меняются редко: сервер для статики, фреймворк бэкенда, интеграция с платёжной системой. При этом понимание их общей модели необходимо всем разработчикам.

Недавно разработчики придумали очередной стандарт описания ответственных за участки кода, см.:
О владельцах кода

Коротко опишите эти штуки и их взаимодействие, без деталей. Дайте ссылки на код и точки входа в него — откуда всё начинает работать. Прикрепите контакты тех, кто поможет погрузиться глубже. Положите эту информацию в ридми репозитория или ещё куда‑то у всех на виду.

Недавно разработчики придумали очередной стандарт описания ответственных за участки кода, см.:
О владельцах кода

Следите, чтобы код говорил сам за себя

Тут как с зарядкой: всем очевидно, но мало кто делает.

Код — это язык общения разработчиков. Он должен быть чётким, лаконичным, без мусора, смыслы и связи сущностей должны быть очевидны из названий.

Проверить просто: разработчик должен без труда и подглядывания в отладчик объяснять, что делает каждый конкретный файл, каждый модуль, каждая функция.

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

Если без пояснений никак — держите их в коде

Хитрую логику бизнеса и предметной области описывайте в комментариях. Если объяснить коротко не получается — повод задуматься о рефакторинге.

Организуйте ротацию разработчиков

Работа с разными частями продукта — хороший способ повысить осведомлённость команды о том, что, как и где работает. Ещё это отличный повод вернуться к подвисшим багам и в целом улучшить качество существующего код.

В бюро разработчики по очереди дежурят в службе поддержки, где сталкиваются с задачами из самых разных кусочков инфраструктуры бюро. Так они начинают видеть картину целиком и лучше ориентироваться во всех бюрошных продуктах.

Будьте аккуратны, тут легко перегнуть палку и замучать разработчиков частыми принудительными перестановками.

Проверьте окружение

Часто разбираться в коде мешают тормозные системы сборки, агрессивные линтеры, необходимость врубать дополнительные сервисы и всё такое.

Позаботьтесь, чтобы проект на компьютере разработчика работал как можно быстрее и не парил мозг ерундой. Это ускоряет изучение и работу с кодом. А оптимизации, линтеры и прочие заморочки применяйте на уровне создания пул‑реквестов, например.

Что дальше?

Если описанной выше базы нет, то никакие диаграммы, схемы, документы, вики и регулярные встречи для обмена опытом особо не помогут.

Если база есть — проверьте ещё раз дальше отталкивайтесь от конкретных проблем. Во что именно не врубаются разработчики? На чём застревают? Что могло бы им помочь не застрять в будущем? Только не забудьте по ходу дела о самой разработке и не замучайте этим всем коллег :‑)

P. S. Это был совет о веб‑разработке. Хотите знать всё о коде, тестах, фронтенд‑разработке, цеэсэсе, яваскрипте, рельсах и джейде? Присылайте вопросы.

Веб‑разработка
Отправить
Поделиться
Запинить

Рекомендуем другие советы