Мой ответ содержит лишь умозаключение Боба Мартина и мое отношение к документированию. Я не говорю, что так должно быть.
Если вспомнить умозаключение Боба Мартина из книги "Чистый код". Чистый код не требует документирования или требует, но не значительного. Чистый код — это код, который легко читать, понимать и изменять другими разработчиками. Он является выразительным, кратким и организованным.
В своей практике я встречал 3 подхода к документированию:
- Нет документирования (лишь комментарии к отдельным блокам кода)
- Документируют, но только то что захотели
- Документируют все
Когда я документирую что-либо я стараюсь показать 2 вещи:
- структуру без реализации (реализацию можно посмотреть в коде)
- бизнес задачу/ бизнес подход (для чего это нужно?)
Читал статью (оч. давно) про чрезмерное документирование... Но ни разу не встречал.
Чаще всего я видел документирование через MarkDown, UML, OpenAPI, Swagger, просто использование интерфейсов.
По поводу UML это действительно удобно, но не все хорошо читают его. Если речь о новичках как о людях которые недавно в разработке, то UML только усложнит процесс изучения продукта. Если речь о новичках как о людях с опытом которые недавно подключились к вашему проекту, то возможно это упростит процесс изучения продукта.
UML отлично подойдет для описания отношения (классов/объектов) или для взаимодействия модулей. Ни разу не использовал UML для описания (функций/методов), но почему бы и нет? Были случаи когда я использовал просто блок схему для описания поведения (функции/метода)...
Создавая любой вариант документации нужно продумать процесс поддерживания ее актуальности.