Документация == антибиотики

В свете недавних обсуждений про тесты - пара слов про документацию. Я нашёл очень хорошую метафору: написание документации - это приём антибиотиков. Антибиотики спасли сотни миллионов жизней, может быть, больше миллиарда. Ценность открытия антибиотиков для человечества сложно переоценить.

Но внезапно бездумно пить антибиотики по каждому поводу и без - для организма совсем не полезно. В какой-то мере антибиотик является ядом: очень специальным, очень контролируемым, но совсем не витаминкой (хотя слишком много витаминов тоже не полезно).

С документацией дела обстоят ровно так же. Отсутствие документации не всегда == гибель проекта, но в большинстве случаев, если документации нет никакой, это довольно грустно и часто является очень существенной проблемой. С другой стороны, сама по себе документация - это накладные расходы, это не основной функционал, и она не приносит непосредственной пользы пользователю. Документацию надо поддерживать в актуальном состоянии, и чем её больше, тем это сложнее. И в этом смысле документация - это токсичный (если всё хорошо, легко токсичный) asset.

«Внезапно» не всегда документация так уж нужна. Предположим, у нас есть стандартное Spring Boot-приложение, сделанное через Spring Initializer, со, скажем, файлом build.gradle. В Gradle видна зависимость от Spring Data JDBC и от PostgreSQL базы, и в корне проекта лежит docker-compose.yaml, который стартует PostgreSQL. В src/main/resources лежит application.properties, где определены стандартные data source properties.

Вопрос - что стоит документировать в такой ситуации? Возможно, ничего. Ну, может быть, одну строку: «тут всё примерно как вы ожидаете от Spring Boot + Gradle + PostgreSQL», и, может быть, стоит на этом остановиться.

Более того, во всех случаях, когда я видел New Developer Onboarding документы на 5+ страниц, - это было признаком того, что у проекта есть проблемы того или иного сорта. Возвращаясь к метафоре с антибиотиками: если человек пьёт антибиотик каждые два месяца - с высокой вероятностью у него есть проблемы со здоровьем, которые непосредственно антибиотиком не лечатся, и надо смотреть на проблему комплексно.

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

Как правило, хорошая причина для написания новых документов - это либо какое-то нестандартное решение, которое команда была вынуждена принять по какой-то причине, и тут причину и само решение стоит задокументировать. Либо это какая-то хитрая внешняя причина - например: как получить API-ключ, почему между вызовами API вдруг стоит Thread.sleep(18_500) или что-то такого же плана.

Красиво написанный, но длинный документ для какой-то области, где можно обойтись без него, - это, скорее всего, не полезный для организма проекта антибиотик, без которого можно было бы обойтись.