Какую документацию имеет смысл писать? Смотри пост про комментарии в коде: Комментарии в коде Я придерживаюсь мнения, что комментировать ваши POJO, и внутреннее API смысла никакого нет. Комментировать имеет смысл публичное API, которое используется другими командами или вне вашей компании. Но что имеет смысл все таки документировать? Обычно это делается во внутренней вики компании (Например, Confluence). 1) Цели команды, какие задачи (бизнес или не бизнес) она решает. Чтобы вас можно было легко найти по тексту проблемы, которую хочет решить другая команда. И зайдя на страницу вашей команды, сразу стало понятно, чем вы можете быть полезными кому-то еще. 2) Описание основного функционала, который может быть полезен другим командам или вне компании. Это описание фич, которые предоставляет ваша команда. 3) Customer onboarding. Если кто-то захочет использовать ваш функционал, как ему заонбордиться? нужно ли создать какой-то onboarding тикет, или просто начать использовать какое-то публичное API. Нужно подробно описать все шаги, как кастомеру стать вашим клиентом. 4) Public API. Детальное описание API, которое вы предоставляете внешним клиентам (внутри или вне компании). 5) SLOs, SLAs, SLIs. Если есть и применимо к вашему функционалу. 6) Support and Monitoring for Customers. Как ваши клиенты могут трекать состояние вашего сервиса? какие метрики или дашборды они могут использовать? Как связаться с саппортом если у них проблемы? Как поднять тикет, запейджить, написать кому-то и т.д. 7) Описание Архитектуры вашего решения. Не комментарии к коду i++, а диаграммы с описанием высокоуровневой архитектуры и архитектуры тех или иных фич. 8) Internal Support and Monitoring. Детальные метрики, алармы, дашборды, ранбуки для саппорта, которыми будет пользоваться тот, кто саппортит вашу функциональность. 9) Онбординг для новичка вашей команды. Документы, которые нужно прочитать человеку, который только пришел работать в вашу команду. Где найти код, как настроить среду разработки, как тестировать, запускать, деплоить и т.д. Как устроен процесс разработки, релиза и все что потребуется человеку для работы в вашей команде. 10) User Manual, FAQ. Детальное описание того, как пользоваться вашим функционалом со стороны клиента. Описание типичных проблем и их решения. Типичные уточняющие вопросы и ответы на них. 11) Внутренние дизайн доки. Когда вы дизайните новую фичу, компоненту и т.д. вы пишете дизайн док/RFC. Он проходит дизайн ревью и ложится в основу реализации фичи. Имеет смысл этот док сохранить для понимания причин того или иного решения + атачить ссылку на этот документ в code-review и коммитах. Чтобы в системе контроля версий видеть, почему что-то было сделано так и не иначе. 12) Code-style. Если вы создали и договорились про какие-то стили в кодирование, то можно это зафиксировать в виде документа. Это может быть список Code Smells. 13) Team and org chart. Кто менеджер, тим-лид, список всех членов вашей команды. С тем можно поговорить потенциальному клиенту. Как ваша команда вписывается в структуру компании? в каком орге она находится и т.д.