documentation-strategy

Скилл Documentation Strategy помогает спроектировать и поддерживать систему документации для команды или продукта. Он не привязан к конкретной платформе и предлагает сначала разобраться в аудитории, существующих материалах, размере и росте команды, видах работы, которые порождают документацию, и уже используемых инструментах. Такой порядок важен: выбор wiki или docs-сайта без понимания владельцев, читателей и жизненного цикла обычно оставляет команду с большим числом страниц, но без надёжного ответа на вопрос, где искать актуальную информацию. В основе скилла — разделение документации на четыре типа. Reference описывает, что существует: API, конфигурацию, глоссарий, архитектурные схемы и записи решений; для него важны полнота, проверка фактов, поиск, стабильная структура ссылок и версии. How-to объясняет, как выполнить конкретную задачу, поэтому ему нужны предусловия, пошаговые действия, проверенный другим человеком пример и troubleshooting. Explanation отвечает на вопрос «почему это устроено так» и фиксирует контекст, ограничения и ссылки на доказательства. Tutorial ведёт читателя от нулевого состояния к результату и должен иметь последовательность и понятный критерий завершения. Отдельно описываются пять уровней ответственности. Customer-facing материалы требуют редакционной проверки, ясного владельца и высокой свежести. Cross-team документы должны иметь межкомандного владельца и регулярно пересматриваться. Team-internal материалы принадлежат конкретной команде и помогают следующему участнику работы. Personal scratchpad не следует выдавать за официальный источник. Auto-generated документация должна строиться из единственного источника истины и обновляться при изменении кода. Это позволяет не требовать одинаковой бюрократии от README, runbook, внутренней заметки и публичного API. Рабочий процесс начинается аудитом: нужно перечислить документы, их расположение, состояние, дату обновления и реальное использование. Затем каждому материалу назначаются тип и уровень, формируется список пробелов, а устаревшие, дублирующие или относящиеся к исчезнувшим системам документы архивируются либо удаляются. После этого выбирается место хранения по классу материала, назначается владелец с резервным ответственным и задаётся cadence проверки. В скилле приведены ориентиры: customer-facing документы проверяются на каждом релизе и ежеквартально, shared и team-internal — ежеквартально, auto-generated — при каждом изменении. Документация должна быть частью самой работы: новая функция сопровождается обновлением docs, новый процесс — процедурой, архитектурное решение — ADR или записью decision log, а postmortem — обновлением runbook. Для обнаруживаемости нужны рабочий поиск, индексные страницы, взаимные ссылки, синонимы запросов и закрепление самых востребованных материалов. Полезность можно проверять просмотрами, поисковыми запросами без результата, feedback, временем на странице и повторяющимися вопросами команды. Скилл также предлагает практические формы: короткий README отвечает, что это, как запустить и как внести вклад; ADR фиксирует контекст, решение и последствия; runbook содержит доступ, операции, типовые сбои, восстановление и эскалацию. Выбор инструмента вторичен по отношению к дисциплине. Markdown в репозитории удобен для README, ADR и технических документов, wiki — для cross-team и внутренних материалов, docs-сайт — для публичной документации. При выборе проверяются качество поиска, редактор, история версий, права, API-интеграции и стоимость. Скилл отдельно предупреждает о типовых провалах: mega-doc, который никто не читает; несколько источников истины; документы без владельца; примеры, которые перестали запускаться; wiki-могильник; и материалы, написанные «потом». Для AI-инструментов полезны единая структура, metadata, глоссарий и явная пометка архивных страниц, но сгенерированный черновик всё равно требует человеческой проверки.