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

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

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

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

(далее…)

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

(далее…)