Документация — это фича

Документация не является чем-то отдельным от вашего продукта. Она — часть продукта.

Многие разработчики следуют ошибочному паттерну:

  • Создать фичу.
  • Протестировать фичу.
  • Выпустить фичу.
  • Задокументировать фичу.

Пользователи не взаимодействуют с вашим кодом. Они взаимодействуют с вашим интерфейсом, вашими рабочими процессами и вашей документацией. Для пользователя документация — это фича.

Создатели пренебрегают документацией, потому что они уже понимают продукт. Вы знаете, почему приняли те или иные решения. Вы знаете, как работает API. Вы знаете все тонкости.

Пользователь — нет. То, что кажется вам очевидным, для них выглядит загадочно.

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

Хорошая документация снижает трение. Она быстро отвечает на вопросы:

  • Что это?
  • Почему я должен это использовать?
  • Как мне начать?
  • Какой подход лучше всего?
  • Где простой пример?

Цель не в полноте. Цель — в динамике.

Отличная документация обучает паттернам и намерениям. Она объясняет, почему фреймворк работает именно так. Это делает пользователей эффективнее.

Документация влияет на ваш бизнес неявными способами:

  • Уровень внедрения (adoption rates).
  • Скорость онбординга.
  • Затраты на поддержку.
  • Рост сообщества.
  • Developer experience.

Влияние хорошей документации трудно заметить сразу. Но отсутствие плохой документации заметно мгновенно.

Помните, что документация нужна и вам самим. Она сохраняет ваши знания для ваших будущих версий. Она фиксирует решения, чтобы вам не пришлось заново искать ответы спустя месяцы.

Качество продукта и качество документации взаимосвязаны.

  • Запутанное ПО требует больше документации.
  • Понятное ПО требует меньше.
  • Хорошая документация обнажает плохой дизайн.

Перестаньте относиться к документации как к чему-то второстепенному. Используйте её, чтобы добиться ясности. Ясность улучшает ваш дизайн. Улучшенный дизайн улучшает ваш продукт.

Источник: https://dev.to/stinklewinks/documentation-is-a-feature-228n