Большинство документаций к продуктам для разработчиков — плохие. Не потому что авторы не старались, а потому что документацию писал инженер, который знает продукт насквозь, и ему «всё очевидно». А человеку, который видит продукт впервые, — ничего не очевидно.

Четыре типа документов — не путайте их между собой

Есть классическая модель. Вся документация делится на четыре типа, и каждый решает свою задачу:

Обучающие материалы (уроки). (далее…)

(далее…)

Пока diff небольшой, в нас просыпается хранитель инженерной чистоты: мы спорим о нейминге, замечаем лишний пробел, обсуждаем, стоило ли выносить логику в helper, но когда правка разрастается до тысяч строк, строгость уступает другому подходу: CI зелёный, тесты прошли, код выглядит вроде неплохо — можно жать Approve.

(далее…)

Обычно это не происходит за один день. Сначала на встречах всё выглядит нормально. Люди кивают, договариваются, задачи расходуются по исполнителям. Руководителю кажется, что команда в контуре, помех нет, напряжение работает. А потом после созвона начинается совсем другая жизнь: в личных сообщениях обсуждают решение, в чатах без начальника спорят, кто опять всё сломал, а на кухне или в курилке звучит привычно: «ну с ним всё понятно».

Многие руководители на данный момент делают наиболее удобный для себя вывод: команда токсична. Или обиделась. Или не умеет разговаривать прямо.

(далее…)