Блог Томаша Фиялковского о программировании

Нет смысла в точности, когда вы даже не знаете, о чём говорите. В профессиональной жизни мне не раз встречались формулировки вроде «всякая система должна иметь документацию». Обычно по таким требованиям кто‑то из команды готовил документ с пометкой «документация». Часто это был принудительный документ, который ни на что не влиял с точки зрения удобства использования системы и ничего не упрощал.

В этом материале я хочу предложить свой трёхкомпонентный подход к задачам и проблемам, связанным с документацией.

Во‑первых, определите, какую проблему должна решать документация. Сообщество IT нередко воспринимает создание документации как обязательное требование, которое выполняют неохотно. Главная цель документации — достижение конкретного результата или решение определённой проблемы — часто не осознаётся. Не учитывая цель, мы готовим документ, который якобы должен отвечать на все вопросы всех заинтересованных сторон, если вообще отвечает на какие‑то. Приведём несколько примеров целей и проблем, которые документация может призвана решать:

  • архитектура системы сложна и трудно объяснима;
  • время адаптации новых сотрудников в проекте велико, и его требуется сократить;
  • команда эксплуатации (Ops) испытывает трудности с развёртыванием ПО, подготовленного разработчиками;
  • другие команды жалуются на интеграцию с нашей библиотекой.

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

Во‑вторых, подумайте, можно ли решить проблему иначе, чем документацией. Создание документации часто воспринимается как универсальное средство, но бывает разумнее найти и устранить корень проблемы, чем наклеивать пластырь в виде ещё одного документа. Если архитектура сложна, вместо того чтобы писать объёмную документацию, объясняющую все тонкости, лучше потратить время на упрощение архитектуры, чтобы её было легче понять. Если адаптация сотрудников занимает много времени, стоит узнать причину: плохое качество кода, несоблюдение стандартов, отсутствие модульности? Во многих таких случаях корректировки в коде и процессах решат проблему лучше, чем документация, и упростят жизнь всем пользователям кода.

Если команда эксплуатации испытывает трудности с развёртыванием, вместо подготовки детальных спецификаций развёртывания имеет смысл применить практики DevOps, ввести стандартизированные и понятные процедуры или подход «you build it, you run it». Если проблемы с использованием библиотеки, прежде всего поработайте над API: убедитесь, что интерфейс чётко определён, прост в использовании, методы и типы однозначны.

В‑третьих, выберите подходящую форму документации. Не хочу быть неправильно понятым: я не против письменных материалов. Часто именно документация — лучший способ решить многие задачи. Однако важно выбрать правильную форму. Для описания фреймворка, с которым будут интегрироваться другие команды, лучше всего подойдёт обучающий туториал, тогда как тот же туториал мало поможет разработчикам, которые сами развивают этот фреймворк. Для описания архитектурных решений можно использовать записи об архитектурных решениях (ADRs). Разные ситуации требуют разных форм документации; иногда в одной системе понадобится множество форм.

Если диаграмма непонятна без устного объяснения, скорее всего, она пытается показать слишком много концепций одновременно и её следует разбить на несколько более простых. Если кто‑то просит вас подготовить документацию, прежде чем что‑то делать, спросите: какую проблему мы пытаемся решить? И решите её правильным способом.

Programming Chi (или Qi) — блог о скромных идеях, багах и ошибках, с которыми я сталкиваюсь ежедневно. К счастью, вместе с неудачами случается немало успехов и элегантных решений, о которых я тоже надеюсь писать.