Техническая документация — это не один документ, а набор разных артефактов, и каждый пишет свой автор. Из статьи вы узнаете, какие семь видов документации нужны IT-команде, как понять, что вообще стоит документировать, и как собрать информацию для документа, если решение принимали полгода назад.
Дальше разберём практику: как оформить документ, чтобы его дочитали до конца, где его опубликовать, как связать документацию с задачами и проектами, как не дать ей устареть вместе с кодом и по каким критериям выбирать инструмент для команды разработки.
Как создать техническую документацию?
Создание технической документации сводится к четырём шагам. Команды чаще ошибаются не в оформлении, а на первом шаге: документируют всё подряд или не то, поэтому порядок здесь важнее объёма.
- Определите, что именно нужно задокументировать, и отсеките остальное.
- Соберите информацию у того, кто принимал решение, пока он ещё в команде.
- Оформите документ так, чтобы его прочитали, а не пролистали.
- Опубликуйте его там, где работают те, кому он понадобится.
Но прежде чем идти по шагам, стоит понять, какой документ вы вообще пишете: от вида зависит и объём, и автор, и срок жизни.
Какие виды технической документации нужно учитывать?
IT-команде хватает семи видов документации, и каждый закрывает свой вопрос:
- README — как запустить проект;
- API-документация — как к нему обратиться извне;
- ADR — почему архитектура именно такая;
- Техническое задание — что нужно сделать до старта разработки;
- Runbook — что делать дежурному, когда всё упало;
- Postmortem — почему упало и что менять;
- Changelog — что изменилось между версиями.
Русскоязычные материалы о технической документации обычно описывают её через стандарты ЕСПД: техническое задание, пояснительная записка, описание программы. Это документы, которые команда сдаёт наружу — заказчику или по договору.
Но большую часть рабочего времени разработчик читает другие документы, которые команда пишет сама себе. В стандартах их нет, и именно они чаще всего не написаны.
README и документация репозитория
README — первый файл, который открывает разработчик после клонирования репозитория. Он отвечает на один вопрос: как запустить это у себя и не потратить на это день.
Рабочий README держится на минимуме: одна строка о назначении проекта, установка и первый запуск, пример вызова, описание переменных окружения и конфигурации. Всё остальное выносится в отдельные документы и линкуется.
Проверка простая: дайте README новому разработчику и посмотрите, дойдёт ли он до работающего проекта, ни разу вас не спросив. Каждый вопрос — это пропущенный пункт.
API-документация
API-документация нужна тем, кто вызывает ваш сервис снаружи: соседней команде, интегратору, клиенту. Она описывает эндпоинты, форматы запроса и ответа, коды ошибок и способ авторизации.
Главное отличие от README — читатель не видит ваш код и не может в него заглянуть. Поэтому каждый эндпоинт нужен с живым примером запроса и ответа, а не только со схемой полей.
Отдельно опишите ошибки. Разработчик обращается к документации чаще всего в тот момент, когда получил код 4xx и не понимает, что именно сделал не так.
Architecture Decision Records (ADR)
ADR фиксирует не саму архитектуру, а причину, по которой её выбрали. Через год команда помнит решение, но не помнит, какие варианты отвергли и почему, и переспорить решение заново становится дешевле, чем разобраться.
Формат предложил Майкл Найгард в заметке «Documenting Architecture Decisions» в ноябре 2011 года. Он описал ADR как короткий текстовый файл на одну-две страницы, где каждая запись описывает набор действующих сил и одно решение в ответ на них.
Разделов пять: заголовок, контекст, решение, статус и последствия. Контекст Найгард требует писать нейтрально, без оценок, а последствия — включая отрицательные. Статус меняется со временем: предложено, принято, устарело, заменено другим решением.
Техническое задание (ТЗ)
Техническое задание описывает, что нужно сделать, до того как разработка началась. Оно фиксирует требования к фиче, границы работы и критерий, по которому её примут.
В российской практике ТЗ живёт в рамках ЕСПД: содержание и оформление задаёт ГОСТ 19.201-78. Стандарт разрешает уточнять состав разделов, вводить новые и объединять существующие в зависимости от особенностей программы, поэтому формальность здесь ниже, чем кажется по названию.
Во внутренней разработке ТЗ обычно короче стандарта и пишется на одну фичу: задача, ограничения, что считается готовым. Ценность даёт не объём, а строка про критерий приёмки — именно её потом цитируют в споре.
Runbook
Runbook — инструкция для дежурного инженера на случай инцидента. Её читают ночью, в спешке и без времени разбираться, поэтому она пишется шагами, а не рассуждениями.
Хороший runbook отвечает на три вопроса: как понять, что случилось именно это, что нажать, чтобы вернуть сервис, и кого разбудить, если не помогло. Теорию из него выносят в ADR, ссылкой.
По жанру runbook ближе всего к рабочему регламенту: тот же жёсткий порядок действий и тот же ответственный на каждом шаге. Как такие документы составляют и внедряют в команде, разобрали в статье о регламентах в работе.
Postmortem-отчёты
Postmortem разбирает инцидент постфактум. В книге Site Reliability Engineering, которую команда Google выпустила в O'Reilly в 2016 году, он определён как письменная фиксация инцидента, его последствий, предпринятых действий, коренных причин и последующих шагов, чтобы инцидент не повторился.
Ключевое слово там — blameless. Разбор исходит из того, что все участники действовали добросовестно, исходя из той информации, которая у них была, и ищет причины в системе, а не виноватых. Иначе люди перестают сообщать о сбоях.
В той же главе перечислены поводы для разбора: видимый пользователю простой или деградация выше порога, любая потеря данных, вмешательство дежурного вроде отката или перенаправления трафика, слишком долгое решение и отказ мониторинга, когда о сбое узнали вручную.
Changelog и release notes
Changelog — список заметных изменений между версиями. Проект "Keep a Changelog" Оливье Лакана описывает его как выверенный, хронологически упорядоченный список для каждой версии и предлагает шесть типов записей: добавлено, изменено, устарело, удалено, исправлено, безопасность.
Главный принцип оттуда: changelog пишется для людей, а не для машин. Поэтому автосборка из git log его не заменяет — коммит фиксирует шаг в эволюции кода, а раздел changelog описывает заметную разницу для того, кто этим продуктом пользуется.
Release notes решают ту же задачу для внешнего читателя и говорят его языком: не «отрефакторили очередь», а «письма перестали дублироваться». Внутренний changelog при этом остаётся техническим.
Как определить, что нужно задокументировать?
Документировать всё — верный способ не документировать ничего: объём растёт, актуальность падает, доверие к документации исчезает. Поэтому нужен критерий отбора, а не полнота.
Рабочих критериев два. Первый: вопрос, который в чате команды задают повторно. Если на него ответили дважды, ответ пора выносить в документ. Второй: решение или процедура, которые знает один человек.
Второй критерий важнее. Знание, которое живёт в одной голове, — это не документация, а риск: он реализуется в отпуске, на больничном или при увольнении, и всегда в неудобный момент.
Как собрать информацию для документа?
Информация для технического документа почти никогда не лежит готовой. Её собирают из трёх источников, и порядок здесь тоже имеет значение.
Начните с автора решения: у него в голове есть то, чего нет ни в коде, ни в тикетах, — отвергнутые варианты. Дальше идут код и коммиты: они показывают, что было сделано на самом деле, а не что планировали. Восстанавливать историю проще, когда задачи и коммиты уже связаны, — для этого платформа для совместной работы Strive интегрируется с GitHub и с GitLab.
Третий источник — реальный инцидент. Документ, написанный по следам настоящего сбоя, точнее любого умозрительного описания: в нём остаются те детали, которые в теории выглядят необязательными.
Как оформить документ для восприятия?
Технический документ читают не подряд, а по диагонали, в поиске нужного куска. Значит, оформление решает не эстетику, а скорость поиска ответа.
Что работает:
- короткие абзацы и нумерованные шаги вместо сплошного текста;
- код в отдельном блоке, а не внутри строки;
- таблица там, где сравниваются параметры;
- схема там, где текст описывает связи между элементами;
- единые термины: один объект называется одним словом по всему документу.
Полезен и подход информационного стиля Максима Ильяхова: убрать стоп-слова, то есть балласт, который ничего не добавляет к сообщению. В технической документации это особенно заметно — вводные обороты удлиняют текст, но ни одного вопроса не закрывают.
В трекере задач Strive документ собирается сразу в нужном виде: заголовки, списки, цитаты, таблицы, чекпункты и вставка кода доступны прямо в редакторе, а к разделам можно оставлять комментарии, не уходя в мессенджер.
Как опубликовать документ для команды?
Документ, о котором никто не знает, не существует. Публикация — это не «сохранить файл», а положить документ туда, где работают люди, которым он понадобится.
Ссылка в чате для этого не годится: сообщение утонет в ленте к вечеру, а через месяц его не найдёт даже автор. Документация должна лежать в общем пространстве команды, рядом с её проектами и задачами.
Часть документов нужна и за пределами команды: API-документацию читают интеграторы, релизные заметки — клиенты. В таск трекере Strive документ можно сделать публичным по ссылке, и тогда его откроют те, кто в сервисе не зарегистрирован.
Как вести техническую документацию?
Написать документ проще, чем удержать его живым. Ведение документации — отдельная работа из трёх частей:
- Связать документ с той задачей или проектом, к которым он относится.
- Поддерживать его в актуальном состоянии, когда меняется код.
- Вести в инструменте, который для этого приспособлен.
Как связать документацию с задачами и проектами?
Документ, который лежит отдельным файлом, теряется первым. Он не привязан ни к чему, и найти его можно, только если помнишь название.
Поэтому документацию организуют структурой, повторяющей структуру работы. В сервисе для управления задачами Strive есть три уровня: обычный документ, документ внутри группы и поддокумент, вложенный в основной. Из них собирается древовидная структура — например, группа на сервис, документ на подсистему, поддокументы на её части.
Второй способ связи — перекрёстные ссылки. В редакторе есть отдельный блок «Ссылка на документ», поэтому README ссылается на ADR, а runbook на то же архитектурное решение, и читатель не ищет соседний документ поиском.
Живёт эта структура в пространстве команды, рядом с её проектами, и открывается прямо из проекта. Отдельного «диска с документами» не появляется: разработчик остаётся там же, где ведёт задачи.
Как поддерживать документацию актуальной?
Документация устаревает вместе с кодом, и это происходит тихо: текст выглядит рабочим, но описывает поведение прошлого релиза. Такой документ хуже отсутствующего, потому что ему верят.
Помогают две вещи. У каждого документа должен быть владелец — человек, а не отдел. И у документа должен быть повод для пересмотра, привязанный к коду: рефакторинг затронутого модуля, смена контракта API, изменение процедуры деплоя.
Чтобы правки можно было отследить, нужна история версий. В системе организации командной работы Strive она показывает, кто и когда редактировал документ, позволяет сравнить редакции и восстановить нужную версию, если правка оказалась ошибочной.
Какие инструменты упрощают ведение документации?
Инструменты для технической документации делятся на четыре группы, и выбор между ними — это выбор компромисса.
- Markdown в репозитории — документ живёт рядом с кодом и ревьюится вместе с ним, но виден только разработчикам и теряется при росте объёма.
- Генераторы из кода (Doxygen, Sphinx, Javadoc) — документация не расходится с сигнатурами, но описывает только код и не отвечает на вопрос «почему».
- Вики и базы знаний — удобно искать и писать всем, но документация живёт в стороне от задач и быстро устаревает.
- Таск-менеджер с документацией — документы лежат там же, где работа команды, и обновляются в том же контуре.
Последний вариант закрывает главную проблему остальных: разработчику не нужно переключаться между инструментами, чтобы свериться с документом. Как выстроить документацию всей компании, а не только техническую, разобрали в статье о ведении документации компании.
Как выбрать инструмент для технической документации?
Инструмент оценивают по одному признаку: будут ли документацией пользоваться каждый день. Из него раскладываются пять критериев:
- редактор понимает технический текст — блоки кода, таблицы, чекпункты;
- документы связаны с задачами и проектами, а не лежат отдельно;
- есть история версий, чтобы видеть изменения и откатывать правки;
- доступ настраивается по ролям, а нужные документы можно открыть наружу;
- есть связь с репозиторием, чтобы задачи и коммиты не жили порознь.
Под эти критерии подходит раздел «Документация» в системе управления задачами Strive: документы ведутся рядом с задачами в древовидной структуре, редактор поддерживает таблицы, чекпункты и вставку кода, история версий позволяет вернуться к прежней редакции, доступ настраивается по ролям, а отдельные документы открываются по публичной ссылке. Интеграция с GitHub и GitLab связывает задачи с коммитами, а данные хранятся в России.
