Документация, которая живёт: процесс, шаблоны, поиск
Минимальный набор форматов
Если доков слишком много и они огромные, ими никто не пользуется. Оставьте три вида: RFC — что решили и зачем; ADR — архитектурные выборы; how‑to — короткие шаги.
У каждого документа есть владелец и дата пересмотра. Срок вышел — обновите или уберите в архив с пометкой, почему не нужно.
Пишите короче: одна страница лучше, чем десять. Детали — в отдельное how‑to.
- Только RFC, ADR и how‑to
- Владелец и дата пересмотра
- Архив с объяснением, почему устарело
Ритуалы обновления
Обновление дока — часть задачи. Сделали фичу — добавили пару строк в how‑to или обновили ADR. Это минуты, но экономит часы.
Раз в месяц делайте "doc day": почистить старое, добавить примеры команд, скриншоты, схемы. Это дешёвый порядок.
Заведите напоминания и ротацию ответственных, чтобы doc day не зависел от одного человека.
- Док — часть Definition of Done
- Ежемесячный doc day
- Больше примеров и скриншотов
Поиск и связь с задачами
Доки читают, если их легко найти: оглавление, тэги, поиск по заголовкам и коду. В задачах и запросах на слияние кладите ссылки на нужный док.
Если документ старше 90 дней, ставьте баннер "пора пересмотреть" и назначайте ответственного.
Держите одну "страницу входа" со ссылками на главное — это экономит время новичкам и снижает вопросы.
Навигация
- Оглавление + тэги + поиск
- Быстрые ссылки на ключевые темы
- Фильтры: RFC, ADR, how‑to
Связь с кодом
- PR ↔ ADR/How‑to для истории
- Баннер пересмотра для старых доков
- Напоминания владельцам о пересмотре
Примеры и применимость завтра
Док нужен, если помогает завтра. Добавляйте готовые команды, примеры запросов, скриншоты. Пишите шагами: что делать, кто отвечает, за сколько времени.
Убирайте воду: короткие абзацы, списки, таблицы. Тогда документ живёт дольше.
Сложный шаг? Запишите короткое видео или сделайте gif — быстрее, чем длинный текст.
- Готовые команды и запросы
- Шаги с ответственными и сроками
- Меньше воды — больше конкретики
Качество и доступность
Линтеры на битые ссылки, единый стиль заголовков и читаемые иллюстрации. Для распределённых команд — короткое резюме на английском.
Меньше плотности текста: короткие абзацы, списки, таблицы, чек‑листы.
Сделайте одностраничный гайд по стилю: как называем заголовки, как пишем примеры, каких слов избегаем. Это снижает разнобой и ускоряет ревью.
- Линтеры ссылок и стиля
- Короткое резюме на английском
- Списки/таблицы вместо полотен текста
Архивация и борьба с шумом
Если док не меняли 3–6 месяцев — на пересмотр. Устаревшее в архив с пометкой: сменился стек, процессы или сервис.
Это снижает шум в поиске и экономит время адаптации новичков.
Раз в месяц 30 минут на чистку: помечайте старое, переносите в архив и обновляйте ссылки.
- Пересмотр каждые 3–6 месяцев
- Архив с причиной устаревания
- Чистый поиск и быстрая адаптация новичков