Про документацию

Кент Бек в своей рассылке наваливает базы про документацию. Суть идеи в том, что сама по себе документация никому не нужна. Что нужно – наличие ответов на конкретные вопросы, знание того, как работает система, и как ее изменять чтобы она не поломалась. И решение о том, нужна ли документация в конкретном месте или нет, это всегда трейдофф.

Факторы, говорящие о том, что документация нужна:

👉Большая потенциальная аудитория читателей. Условно говоря, документация для публичного фреймворка имеет намного больше смысла, чем внутреннего класса, который за все время увидит только три человека.
👉Стабильность. Чем меньше меняется система, и чем более она стабильна, тем меньше костов на поддержание актуальной документации, тем больше в ней смысла.
👉Низкая цена затрат на документацию. Если для того, чтобы написать доки, вы откладываете какие-то важные продуктовые задачи, приносящие ценность бизнесу – скорее всего, вы делаете что-то не так.

Вместо траты время на документацию, можно рассматореть альтернативные способы добиться того же результата:

👉Упрощать систему. Простому коду и архитектуре не нужна документация.
👉Живые коммуникации: парное программирование, рассказы про устройство системы, разговоры за обедом.
👉Тесты. Тут все понятно – при изменении системы приходится менять и тесты, поэтому они легко сохраняют свою релевантность.