Post #1528

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