Практика и ресурсы: как поставить письмо в процесс команды

В команду вышел сильный инженер, который умел писать. За год он оставил одиннадцать ADR, переписал README так, что новый человек разворачивал окружение за полдня, и завёл привычку выносить спорные решения в короткий документ до начала работы. Через год он ушёл в другую компанию.

Ещё через полгода ADR в репозитории по-прежнему одиннадцать. README отстал на две мажорные версии. Спорные решения снова обсуждаются в треде и заканчиваются словами «ну давай так и сделаем». Никто ничего не отменял, никто не был против, все считали, что писать полезно.

Это не история про плохую команду. Это ровно то, что происходит, когда практика письма держится на человеке. Навык одного человека не масштабируется и не переживает его уход. Письмо остаётся в команде только тогда, когда прикреплено к событиям, которые происходят и без него, и подпёрто проверками, которые срабатывают без напоминаний.

Последняя глава трека — про это. Двенадцать предыдущих учили писать конкретные жанры: как устроен ADR, чем RFC отличается от протокола, что делает постмортем документом, меняющим систему. Эта глава — про то, что делать в понедельник: как измерить текущее состояние, куда прикрепить документы, что автоматизировать, что мерить, как распознать бумагу, которая пишется ради процесса, и где брать материал дальше.

Два контура, которые постоянно путают

Когда в компании говорят «надо улучшить документацию», под этим скрываются две разные задачи с разными решениями. Их смешение — главная причина, почему инициативы вокруг документации умирают через квартал.

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

Работают оба контура вместе, и начинать разумно со второго — он даёт видимый результат за недели, а первый требует личного времени, которое команда вам не выделит.

Личный контур: навык растёт от переписывания, а не от объёма

Инженер за неделю пишет описания PR, комментарии на ревью, ответы в чате поддержки, статус в тред. Слов — тысячи. Роста — ноль, если ни один из этих текстов не был переписан и ни на один не пришёл разбор. Механика та же, что в любом навыке: рост даёт не повторение, а повторение задачи на границе возможного с быстрой обратной связью — то, что Андерс Эрикссон назвал deliberate practice (Ericsson, Krampe, Tesch-Römer, 1993). Написать двадцатый раз то же описание PR теми же оборотами — это не практика, это привычка.

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

Разбор: правило команды про документацию

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

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

Разберём, почему это не работает — и это разбор не про стиль, а про механику.

• Нет читателя. Адресат — «все члены команды», то есть никто. Человек, читающий это, не понимает, относится ли правило к нему сейчас.
• Нет решения. После прочтения человек не делает ничего иначе. Проверьте: назовите действие, которое изменится завтра. Его нет.
• Нет момента. «При изменении функциональности» — это когда? В момент коммита, перед релизом, на ретроспективе?
• Нет проверяемого условия. «Актуальное состояние» и «своевременно» нельзя ни подтвердить, ни опровергнуть. Значит, нарушение никогда не будет замечено.
• Ответственность размазана. «Лежит на всей команде» = не лежит ни на ком; это классическая диффузия ответственности, а не распределение.

Итог: текст написан, чтобы он был. Это документ про документы, сам провалившийся тест на читателя и решение — тот самый тест, с которого начинается глава Читатель и решение. Теперь то же правило, переписанное под конкретного человека в конкретный момент.

Кому: автору PR, который меняет публичное поведение сервиса — эндпоинт, формат события, переменную окружения, команду запуска.

Что сделать: в том же PR правишь файл рядом с кодом. Эндпоинты — docs/api.md, запуск — README.md, формат событий — docs/events.md.

Как это проверяется: job docs-check падает, если изменён internal/api/**, а docs/api.md не изменён. Если документ правда не нужен — метка docs-not-needed на PR; метка остаётся в истории, раз в квартал мы смотрим, что под ней прячется.

Кто владелец: docs/api.md — команда @team-payments по CODEOWNERS, ревью обязательно.

Если правило мешает: пиши в #docs-guild. Правило меняется пулл-реквестом в этот же файл, а не разговором.

Что изменилось. Появился адресат («автор PR, который…»), появился момент («в том же PR»), появилось проверяемое условие (job в CI), появился владелец файла, появился легальный способ не выполнять правило — и этот способ оставляет след. Последнее важнее, чем кажется: правило без легального обхода обходят нелегально, и вы теряете данные о том, где оно мешает.

Разбор: отчёт руководителю о работе с документацией

Второй пример — жанр, который инженер пишет, когда хочет продолжения инициативы.

В этом квартале мы провели большую работу по улучшению документации. Создано 34 новых страницы в Confluence, актуализировано 12 существующих, проведён воркшоп по техническому письму. Команда стала более сознательно относиться к документированию, культура улучшилась.

Читатель — руководитель, который решает, оставлять ли на это время в следующем квартале. Из текста он этого решения принять не может: все числа описывают произведённый объём, а не изменившееся поведение. «34 страницы» одинаково хорошо описывают ситуацию, в которой стало лучше, и ситуацию, в которой в вики стало на 34 страницы мусора больше. «Стала более сознательно» — не наблюдаемо.

Прошу решение: оставить в следующем квартале роль дежурного по документации — 4 часа в неделю, это 2,5% времени команды. Что изменилось. Новый инженер делает первый деплой на второй день вместо девятого (замер по трём последним выходам). Повторяющиеся вопросы в #payments-support: было 61 в месяц, стало 18. Из семи крупных решений записаны шесть, кварталом раньше — одно из девяти. Что не сработало. Воркшоп по письму: через месяц ни одна привычка не изменилась, повторять не буду. Сработали проверка docs-check в CI и правило «новичок правит онбординг своим первым PR». Чем рискуем, если не продлить. Документов без владельца сейчас 23%; без дежурного доля вернётся к прошлогодним 60% за два-три квартала, и первым это почувствует онбординг.

Тот же квартал, те же события, но текст обслуживает решение. Дороже всех стоит строка «что не сработало»: она делает отчёт источником данных, а не рекламой. Как разговаривать вверх на языке решений — в главе Работа вверх.

Журнал правок: три записи в неделю

Единственная личная практика, которая надёжно даёт рост, — короткий журнал. Не «полезные советы», а собственные ошибки в категориях.

Через квартал у вас 30–40 записей и виден личный топ-3 повторяющихся ошибок. Чинить надо его, а не абстрактную «ясность». У большинства инженеров этот топ выглядит одинаково: вывод в конце, субъект не назван, термин не определён.

Замер: узнайте, что у команды на самом деле, прежде чем что-то менять

Внедрение без замера — это лотерея: вы почините то, что болит у вас, а не то, что стоит команде дороже всего. Замер занимает один день и даёт четыре числа.

1. Секундомер онбординга. Возьмите следующего нового человека и попросите записывать время до трёх событий: собранный проект, пройденные тесты, первый деплой в тестовую среду. Не помогайте — записывайте, где он застрял. Это самый честный тест документации, потому что новый человек ещё не умеет достраивать недостающее по памяти. Детально — в главах README и Руководства, про роль в найме — онбординг.

2. Повторяющиеся вопросы. Выгрузите вопросы из канала поддержки за 30 дней и сгруппируйте. Каждая группа из трёх и более одинаковых вопросов — это либо отсутствующий документ, либо документ, который не находится, либо продукт, который стоило починить вместо документа. Третий вариант встречается чаще, чем принято думать: подробнее — в главе Микрокопирайтинг.

3. Доля записанных решений. Возьмите десять крупных изменений за квартал из истории репозитория и поищите для каждого ADR или RFC. Отношение — ваша базовая линия. Значение 1 из 10 нормально для старта, значение 10 из 10 подозрительно: скорее всего, ADR пишут ради процесса.

4. Возраст документации. Тридцать секунд в терминале:

# Дни с последней правки по каждому markdown-файлу, самые запущенные — сверху.
git ls-files '*.md' | while read -r f; do
  last=$(git log -1 --format=%ct -- "$f")
  echo "$(( ( $(date +%s) - last ) / 86400 )) $f"
done | sort -rn | head -20

Смотрите не на среднее, а на хвост: документы старше двух лет либо вечны по природе (ADR — запись о прошлом, он и не должен меняться), либо мертвы. Разделить одно и другое можно только глазами, зато быстро.

Запишите четыре числа в один файл с датой. Через квартал вы будете единственным человеком в компании, у которого есть данные о том, помогла инициатива или нет.

Триггеры вместо расписания

Главный структурный приём: документ прикрепляется к событию, которое произойдёт и без документа. Всё, что прикреплено к расписанию («каждую пятницу обновляем вики») или к доброй воле, умирает при первом же авральном спринте. Всё, что прикреплено к слиянию PR, к инциденту, к выходу нового человека, живёт ровно столько, сколько живёт сам процесс.

Обратите внимание на нижнюю петлю: сигнал читателя чинит либо документ, либо правило. Если один и тот же документ приходится чинить третий раз, ломается не документ, а триггер или шаблон.

Стартовый набор триггеров, который можно принести на ретроспективу целиком:

Правило чтения таблицы: строка без проверки не работает. Она держится на памяти конкретных людей и исчезнет вместе с ними — ровно как в истории из начала главы.

Definition of Done и шаблоны: почему короткое живёт, а длинное нет

Первое, что делает команда, решившая «писать больше», — добавляет пункт в Definition of Done: «документация обновлена». Через месяц галочка стоит на всех задачах, а документация в прежнем состоянии. Причина простая: пункт не проверяем, а непроверяемый пункт превращается в ритуал за две итерации. Про работу с DoD и критериями — в критериях приёмки и артефактах Scrum.

Проверяемая формулировка выглядит иначе: не «документация обновлена», а «docs-check зелёный либо на PR стоит docs-not-needed». Разница в том, что второе может быть ложным, а первое — нет.

То же с шаблонами. Вот шаблон описания PR, который встречается в тысячах репозиториев:

## Description
<!-- Please describe your changes in detail -->

## Motivation and Context
<!-- Why is this change required? What problem does it solve? -->

## How Has This Been Tested?

## Types of changes
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change

## Checklist
- [ ] My code follows the code style of this project
- [ ] My change requires a change to the documentation
- [ ] I have updated the documentation accordingly
- [ ] I have added tests that prove my fix is effective

Что с ним не так, если разбирать по-русски. Четырнадцать пунктов, из которых одиннадцать — галочки. Галочка My change requires a change to the documentation отдаёт автору роль судьи в собственном деле и стоит одну секунду: снял — и проверка пройдена. Раздел How Has This Been Tested? в половине PR заполнен словом locally. Шаблон длиннее среднего описания, поэтому его сносят целиком или оставляют пустым — и то и другое ревьюер видит каждый день и перестаёт замечать.

Рабочий вариант — три вопроса, на которые нельзя ответить галочкой:

## Что меняется для того, кто этим пользуется
<!-- Одно предложение. Если ничего — напишите «внутреннее изменение». -->

## Почему так, а не очевидной альтернативой
<!-- Два-три предложения. Если решение дорого откатить — ссылка на ADR вместо текста. -->

## Как проверить, что работает
<!-- Команды или шаги, которые ревьюер повторит у себя. -->

Три правила хорошего шаблона: он короче типичного ответа; каждый вопрос требует предложения, а не отметки; на каждый вопрос в шапке есть пример правильного ответа. Четвёртое правило — шаблон живёт в репозитории и меняется PR-ом, иначе через год никто не помнит, зачем там поле «Риски». Про описания коммитов и PR как отдельный жанр — совместная работа в Git.

Автоматика: что машина проверяет, а что нет

Docs as code — не про то, что документы лежат в git, а про то, что к ним применяется тот же аппарат, что к коду: ревью, CI, владельцы, версии. Теория старения документации и структурные средства против него разобраны в главе Почему документация устаревает; здесь — механика, которую можно скопировать.

name: docs-check
on: pull_request

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # 1. Парность: тронул публичное поведение — тронь документ рядом с ним.
      - name: Публичный API изменён без документации
        run: |
          changed=$(git diff --name-only "origin/${{ github.base_ref }}...HEAD")
          if echo "$changed" | grep -q '^internal/api/' \
             && ! echo "$changed" | grep -q '^docs/api.md'; then
            echo "::error::internal/api изменён, docs/api.md — нет."
            echo "Обновите документ или поставьте метку docs-not-needed."
            exit 1
          fi          

      # 2. Примеры исполняются, а не перечитываются глазами.
      - name: Примеры из документации
        run: pytest --doctest-glob='*.md' docs/

      # 3. Битая ссылка — это читатель, который бросил документ на середине.
      - name: Ссылки
        uses: lycheeverse/lychee-action@v2
        with:
          args: --no-progress docs/ README.md

      # 4. Стиль: машина ловит форму, пользу она не видит.
      - name: Стиль
        run: vale docs/ README.md

Линтер стиля — единственный шаг, где нужна осторожность. Vale полезен ровно настолько, насколько узкие у вас правила: он отлично ловит слова-заглушки и запрещённые термины и совершенно бесполезен против бессмысленного документа. Пример собственного правила:

# .vale/styles/Team/Vague.yml — слова, за которыми обычно прячется непроверяемое требование
extends: existence
message: "«%s» — уточните: кто, когда, насколько."
level: warning
ignorecase: true
tokens:
  - timely
  - as needed
  - regularly
  - kept up to date
  - as soon as possible

Правило англоязычное, потому что готовые стилевые пакеты (Google, Microsoft) написаны для английского; для русских документов такой список пишется руками — «своевременно», «по мере необходимости», «регулярно», «в актуальном состоянии», «в кратчайшие сроки». Это ровно те слова, из которых состоял плохой абзац в начале главы, и линтер ловит их надёжнее, чем ревьюер на десятом документе за день.

Второй элемент механики — паспорт документа в front matter:

---
title: Запуск payments локально
owner: "@team-payments"        # группа, а не человек: люди уходят, группы переживают
review_by: 2026-11-01          # дата, после которой документ считается подозрительным
verified_with: "v2.14.0"       # версия, на которой инструкцию последний раз проходили руками
audience: "новый инженер, первая неделя"
---

И бот, который раз в неделю превращает просроченные документы в задачи:

# Кандидаты на ревизию или удаление: истёк review_by либо срока нет вовсе.
today=$(date +%F)
git ls-files 'docs/**/*.md' | while read -r f; do
  due=$(awk -F': *' '/^review_by:/ {print $2; exit}' "$f")
  [ -z "$due" ] && { echo "БЕЗ СРОКА  $f"; continue; }
  [ "$due" \< "$today" ] && echo "ПРОСРОЧЕН  $due  $f"
done

Важно, чем это заканчивается. Просроченный документ не «требует обновления» — он требует решения владельца из трёх вариантов: продлить срок, пройдя инструкцию руками; переписать; удалить. Третий вариант должен быть таким же уважаемым, как первые два, иначе бот просто генерирует поток задач, которые закрывают без чтения. Удалённый документ честнее устаревшего: он не врёт.

Верхняя половина таблицы — это то, ради чего строится автоматика: она снимает с ревьюера механику, чтобы у него остались силы на нижнюю половину. Автоматика, которая не освобождает человеческое внимание, а добавляет обязательных полей, работает против вас. Как читать чужой текст на то, что машина не видит, — глава Ревью текста, про встраивание проверок в конвейер — тесты в CI и основы CI.

Жизненный цикл документа как объект процесса

Пока документ существует только в голове автора, у него нет состояния: он либо «есть», либо «нет». В процессе у документа появляются состояния и переходы, и именно они определяют, гниёт ли база знаний.

Два перехода делают всю работу. Активный → Подозрительный: без него документ не попадает в поле зрения, пока на нём кто-нибудь не обожжётся. Устаревший → Удалён: без него база растёт монотонно, поиск выдаёт три версии одной инструкции, и читатель перестаёт доверять всему сразу. Архив нужен там, где на документ есть внешние ссылки — из тикетов, постмортемов, чужих вики: такой не стирают, а помечают и убирают из поиска. Переход На_ревью → Удалён выглядит обидно, но это самый дешёвый способ не завести ритуальный документ: если за время ревью не нашлось человека, который скажет «мне это нужно вот для чего», документа быть не должно.

Роли: кто владеет письмом в команде

Владелец документа — всегда группа, а не человек. CODEOWNERS с командой переживает увольнения; owner: @ivan превращается в брошенный файл через полгода.

Дежурный по документации — ротация на неделю, 3–4 часа: разбирает повторяющиеся вопросы недели, чинит то, на чём споткнулся новичок, закрывает просроченные документы решением из трёх вариантов, проходит руками один случайный раннбук. Чего он не делает — не пишет документацию за команду. Как только дежурный становится единственным пишущим человеком, вы вернулись к истории из начала главы, только с расписанием. Гильдия или докс-канал — место, где правила меняются PR-ом; час раз в две недели, повестка из накопившихся предложений. Без него правила окаменевают.

Технический писатель появляется, когда документация, обращённая наружу, перестаёт помещаться в фон инженерной работы: публичный API с внешними интеграторами, продукт с самообслуживанием, сертификация. Он не «пишет за инженеров», а строит систему — информационную архитектуру, стилевой гайд, инструменты, ревью. Инженерная часть — ADR, RFC, постмортем — остаётся у инженеров всегда: технический писатель не может знать, почему выбрали SQS вместо Kafka.

Метрики: три штуки, и все про поведение читателя

Квадрант — не украшение, а инструмент инвентаризации: разложите по нему десять документов своей команды, и картина станет неприятно наглядной. Метрики нужны, чтобы двигать точки вправо и вверх, а не чтобы отчитываться.

Правило: не больше трёх метрик одновременно, и все — про поведение читателя, а не про объём производства. Любая метрика письма ломается по закону Гудхарта («мера, ставшая целью, перестаёт быть хорошей мерой», формулировка Мэрилин Стратерн, 1997), поэтому смотреть на них надо парами: время онбординга вместе с числом страниц, доля ADR вместе с их средней длиной. Расходящаяся пара — сигнал, что метрику начали обслуживать. Про то, как метрики деформируют поведение команды, — в главе Эмпиризм и метрики.

Документы ради процесса: как распознать их в своей организации

Часть документов в любой достаточно большой компании пишется не ради читателя, а ради того, чтобы документ существовал. Делать вид, что это не так, — плохая услуга: человек, которому сказали «пишите документы, они меняют решения», а потом заставили заполнять форму из шестнадцати разделов, делает вывод, что весь разговор о письме — лицемерие.

Признаки ритуального документа, каждый из которых проверяется за минуту:

1. Нельзя назвать читателя. Спросите автора: кто прочтёт? Ответ «руководство», «стейкхолдеры», «для истории» означает, что читателя нет.
2. Нельзя назвать решение. Что изменится, если документа не будет? Ответ «нас поругают» — легальный, но он описывает не решение читателя, а санкцию.
3. Документ пишется после решения. Дизайн-док, который заполняют, когда код в проде, — отчёт о проделанной работе, не документ решения; см. окно принятия решения в главе RFC.
4. Шаблон длиннее содержания. Разделы заполняются одинаково у всех авторов: «Риски: отсутствуют», «Влияние на смежные системы: отсутствует».
5. Важен статус, а не текст. Обсуждают, кто согласовал, а не что написано. Правки касаются формулировок ответственности, а не сути.
6. Единственная ссылка на документ — из чек-листа. Ни в одном тикете, ни в одном треде, ни в одном постмортеме на него не сослались.

Два дешёвых теста. Тест последнего читателя: откройте статистику просмотров или спросите в канале, кто открывал документ за полгода. Тест удаления: уберите документ из поиска на месяц и посмотрите, придёт ли кто-нибудь. Оба безопасны для копии в архиве и дают ответ быстрее любых рассуждений.

Теперь честная оговорка, без которой раздел был бы демагогией. Документ с непривычным читателем — не ритуал. Если текст пишется для аудитора, для регулятора, для комиссии по безопасности — читатель есть, он реален, и решение у него тоже реальное: подписать или не подписать, разрешить релиз или остановить. Такой документ подчиняется тем же правилам, что и все прочие: назван читатель, названо решение. Ритуал — это когда читателя нет ни у кого, включая аудитора; форма живёт по инерции, потому что три года назад её кто-то ввёл, а отменять некому.

Разница видна на одном разделе. Ритуальная версия:

4.2. Оценка рисков. Риски отсутствуют. Влияние на персональные данные отсутствует. Согласовано с отделом информационной безопасности.

Тот же раздел, обслуживающий сразу двух читателей — аудитора и дежурного инженера:

4.2. Данные и риски. Сервис обрабатывает email и phone клиента — это персональные данные. Хранение: таблица payments.contacts, 90 дней, затем автоматическое удаление задачей contacts-gc. Доступ: роль payments-oncall, сейчас 12 человек, список — в iam/roles.yaml. Изменение против версии от 12.02: добавлено поле phone, раньше его не было. Запрос на удаление данных клиента: make gdpr-erase ID=<client_id>, около 4 минут, запись в audit.erasures.

Аудитор получает ровно те факты, которые ищет: категория данных, срок хранения, круг доступа, изменение против прошлой версии. Дежурный получает команду, которую можно выполнить в три часа ночи. Текст один, читателей двое, у каждого своё решение. Это и есть выход из ритуала: не отменить форму, а наполнить её содержанием, полезным кому-то ещё.

Три стратегии для случаев, когда форму отменить нельзя:

• Дешёвое соответствие. Ритуальные поля заполняются генерацией или шаблоном по умолчанию; ваше время уходит на разделы, у которых есть читатель. Час в квартал вместо дня.
• Разделение. Ритуальный артефакт становится тонкой обёрткой со ссылкой на рабочий документ, живущий рядом с кодом. Форма удовлетворена, содержание — в одном месте и в одной версии.
• Разговор с владельцем процесса, подкреплённый числами. «Форма X: 14 авторов, в среднем 3 часа, 42 часа в квартал, за год на неё сослались дважды». Данные меняют процессы, возмущение — нет. Как вести такой разговор — трудные разговоры.

Чего делать не стоит — воевать с формой публично и саботировать её. Это дорого, а исход почти всегда один: форму оставляют, а вас записывают в неконструктивные.

Квартал внедрения: один жанр за раз

Типичная ошибка внедрения — начать со всего сразу: шаблоны, гайд по стилю, миграция вики, обучение. Ничего из этого не приживается, потому что команда не может поменять пять привычек одновременно. Работает другой порядок: замер, один жанр, автоматика под него, второй жанр, привычка ревью, повторный замер.

Четыре правила, без которых план разваливается. Начинайте с жанра, где боль дороже всего — обычно это постмортем (инциденты повторяются) или онбординг (каждый новый человек съедает неделю чужого времени); «архитектурная документация» большая, приятная и не даёт измеримого эффекта в квартале. Первые три документа пишутся публично: автор пишет, команда смотрит и правит вместе — дороже, чем раздать шаблон, и это единственное, что переносит норму, потому что люди копируют образец, а не инструкцию. Никаких больших заездов: «documentation sprint» производит объём, который через полгода гниёт целиком, потому что не прикреплён ни к одному триггеру; если очень хочется заезда, потратьте его на удаление устаревшего. Считайте отказы: метка docs-not-needed и пропущенные постмортемы — данные, а не провал; если метку ставят на половине PR, неверен триггер, а не команда.

Типичные ошибки внедрения

• Воркшоп вместо процесса. Учат писать, не меняя момент, в который положено писать. Через месяц всё как было.
• Обязательный шаблон без примера заполнения. Люди заполняют поля так, как поняли; через квартал документы одного жанра несравнимы между собой.
• Один герой. Всё держится на человеке, который любит писать. Тест: посмотрите, что произойдёт с практикой, если он уйдёт в отпуск на месяц.
• Инструмент вместо привычки. Купили портал документации, перевезли вики, гниение продолжилось на новом движке.
• Документация как наказание. «Раз ты уронил прод, ты и пишешь постмортем» превращает жанр в санкцию и убивает честность разбора — см. постмортем и постмортемы в SRE.
• Ревью текста отдельным советом. Редакционная коллегия из трёх человек становится узким местом за две недели; текст должен ревьюиться тем же потоком и тем же SLA, что и код.
• Метрика объёма. Как только считают страницы, страницы появляются.
• Идеальный старт. Три месяца выбирают систему тегов и информационную архитектуру, не написав ни одного документа.

Программа личной практики на восемь недель

Если внедрять процесс пока не в вашей власти, начните с себя — но с конкретных упражнений, а не с намерения «писать лучше». Каждое занимает меньше часа и делается на рабочем материале.

Через восемь недель у вас есть журнал правок, переписанный набор рабочих документов и — главное — понимание, какие два-три правила лично вам приходится применять сознательно. Это и есть база, с которой стоит идти к команде.

Ресурсы

Ресурсы бесполезны без понимания, какую задачу они закрывают, поэтому — по задачам.

Книги — по одной за раз, а не подряд.

• Jared Bhatti et al. Docs for Developers. Apress, 2021 — https://docsfordevelopers.com/. Ближайшая к этому треку книга: жанры, процесс, метрики, поддержка.
• Joseph M. Williams. Style: Lessons in Clarity and Grace. Почему одно предложение читается легко, а другое нет. Правила, а не вкусовщина.
• William Zinsser. On Writing Well. Глава Clutter окупает книгу.
• Steven Pinker. The Sense of Style. 2014. Та же ясность со стороны устройства чтения.
• Andrew Etter. Modern Technical Writing. Короткое эссе про docs as code.
• Mark Baker. Every Page is Page One. Читатель почти никогда не приходит на первую страницу — и что из этого следует для структуры.

Системы и гайды.

• Diátaxis Даниэля Прокиды — https://diataxis.fr/: четыре жанра и тезис, что смешивать их в одном тексте нельзя. Ранняя версия — Divio documentation system.
• Google developer documentation style guide — https://developers.google.com/style и бесплатные курсы Technical Writing One / Two — https://developers.google.com/tech-writing (короткие, с упражнениями, годятся как командный материал). Microsoft Writing Style Guide — https://learn.microsoft.com/en-us/style-guide/welcome/.
• Write the Docs — https://www.writethedocs.org/, раздел про docs as code и активное сообщество.
• Google SRE Book, культура постмортемов — https://sre.google/sre-book/postmortem-culture/; Google Engineering Practices — https://google.github.io/eng-practices/review/ (гайд по ревью кода, переносится на ревью текста почти дословно).
• GitLab Handbook — https://handbook.gitlab.com/: крупнейший публичный пример компании, работающей письменно; полезен и как образец, и как предупреждение об объёме.

Инструменты.

• Vale — линтер стиля с собственными правилами; markdownlint — формат разметки.
• lychee — быстрый проверщик ссылок для CI.
• MkDocs, Docusaurus, mdBook — статические сайты из markdown в репозитории.
• Backstage TechDocs — документация рядом с сервисом в каталоге; связано с треком платформенной инженерии.
• MADR, adr-tools, Log4brains — шаблоны и утилиты для журнала решений; общий каталог — https://adr.github.io/.
• Redocly и Spectral — сборка и линтинг документации по OpenAPI; doctest, Rust doctests, Go examples — исполняемые примеры.

Образцы для чтения. Полезнее любой книги — час, потраченный на разбор чужой хорошей документации: Stripe и Twilio как эталон справочника с примерами, The Rust Book как эталон обучающего текста, документация Kubernetes как пример разделения жанров на большом объёме, коллекция публичных постмортемов как материал для разбора того, что делает разбор честным.

Мини-итог

• Личный навык письма и процесс письма в команде — разные задачи. Первый лечится переписыванием и обратной связью, второй — триггерами, владельцами и проверками. Воркшоп решает первую задачу и выдаёт себя за решение второй.
• Прежде чем менять что-либо, снимите четыре числа: время до первого успеха новичка, повторяющиеся вопросы, доля записанных решений, возраст документов. Без базовой линии вы не узнаете, помогло ли.
• Документ прикрепляется к событию, которое произойдёт и без него: слияние PR, инцидент, выход нового человека. Всё, что прикреплено к расписанию и доброй воле, умирает в первый аврал.
• Строка процесса без проверки не работает. «Документация обновлена» в Definition of Done — ритуал; «docs-check зелёный либо стоит метка обхода» — правило.
• Машина проверяет ссылки, примеры, соответствие схеме, наличие владельца и парность правок. Нужность документа, порядок изложения и правдивость проверяет только человек — и автоматика нужна ровно затем, чтобы у него на это остались силы.
• У документа есть жизненный цикл с двумя ключевыми переходами: «активный → подозрительный» по сроку и «устаревший → удалён». Без первого гниение невидимо, без второго база знаний растёт монотонно и теряет доверие.
• Метрик не больше трёх, и все — про поведение читателя. Количество страниц — антиметрика: она растёт всегда.
• Часть документов пишется ради процесса. Это распознаётся за минуту по отсутствию читателя и решения, а лечится дешёвым соответствием, разделением ритуальной и рабочей частей или разговором с владельцем процесса, подкреплённым числами. Документ для аудитора — не ритуал: у него есть читатель и решение.
• Квартал внедрения: замер, один жанр, автоматика под него, второй жанр, привычка ревью, повторный замер. Один жанр за раз, первые три документа — публично.

Что дальше

Трек закончен. Дальше письмо перестаёт быть отдельной темой и растворяется в работе — оно понадобится везде, где решение принимает не тот, кто его придумал.

• Если ближайшая задача — архитектурные решения и их запись: архитектурные решения и ADR и системный дизайн.
• Если вы отвечаете за надёжность и разбор инцидентов: реакция на инциденты и постмортемы.
• Если растёте в сторону влияния на команду: обратная связь, трудные разговоры, работа вверх и техническая стратегия.
• Если основная нагрузка — требования, аналитика и процесс: документирование требований, критерии приёмки, фасилитация и коммуникационная нагрузка.
• Если пишете текст, который видит пользователь: микрокопирайтинг. Если впереди смена работы — собеседование, переговоры об оффере и первые 90 дней: там первый написанный вами документ работает как визитная карточка.

А чтобы выбрать следующий трек осмысленно, а не по названию, есть общая карта портала — дорожная карта: видно, какие треки опираются друг на друга и в каком порядке их разумно проходить.