Где болит и что стандартизировать: документация как продукт, а не «свалка»
Любая база знаний разваливается по одному сценарию: у каждого свой стиль, названия «как получилось», документы дублируются и быстро устаревают. Лечится это продуктовым подходом: владельцы и контуры ответственности, стандарты, метрики пользы, регулярная редактура и понятные каналы обратной связи. Начните с «модельной страницы» на один экран — это шаблон, куда попадает всё новое: контекст (для кого), что сделать (шаги/инструкции), ссылки в глубину, дата/владелец/статус («draft/final»), «срок годности» (через сколько пересмотреть), ченджлог внизу, теги. Вводим единые типы артефактов: гайд (как делать X), SOP/процесс (как мы делаем X в команде), ADR/решение (почему выбрали A, а не B), чек-лист (контроль качества), справочник (определения и ссылки). Каждый тип имеет свой короткий шаблон, установленный голос и объём — «писать для людей, не для комиссии»: короткие абзацы, списки, схемы/скриншоты, примеры «до/после». Названия страниц — по формуле «глагол+объект» («Запустить окружение локально», «Снять релиз-кандидата», «Запросить доступ в BI»), чтобы поиск работал естественными запросами. Иерархия каталога строится от задач, а не от оргструктуры: «Продукт», «Инженерия», «Аналитика», «Операции», «Люди» — внутри по сценариям («Релизы», «Доступы», «Данные», «Инциденты», «Найм», «Онбординг»). Ссылки между страницами — как гипертекст, а не «одиночки»: в конце каждого гайда — «см. также», «что дальше», «частые ошибки». Табу — приватная информация в публичных разделах и «вечные документы без владельца». Если документ «ничей», он «никому» не помогает: у каждого артефакта есть владелец или он удаляется. Один автор — «день в неделю» на редактуру лучше, чем «все когда-нибудь». Если хотите, чтобы база жила — назначьте редактора продукта, а не «секретаря».
Поиск и таксономия — сердце базы знаний. Люди не запоминают «где лежит», они пишут в поиск первые два слова. Поэтому каждую страницу пишем «под поисковый сниппет»: первые 160–200 символов — краткий ответ (что это и чем поможет), заголовки — в глагольной форме, таблицы — с ключевыми словами в первых колонках. Таксономия проста: 5–8 верхних тегов по доменам («релизы», «данные», «инциденты», «доступы», «безопасность», «найм», «аналитика», «финансы») и узкие под-теги только при реальной потребности; лейблы для статусов («draft», «final», «deprecated», «policy», «template»). Синонимы/акронимы выносим в маленькие «словарные» страницы, которые ловит поиск. Для широких процессов вводим «индекс-страницы»: «Релиз» собирает гайды по версиям, чек-листы, ролями и роллбэки; «Инциденты» — SLO/алерты/ранбуки/воррум/постмортемы; «Доступы» — политики, формы, SLA, список систем. Чтобы база не «умирала», у каждого раздела есть свой ченджлог и баннер устаревания: автоматическая плашка «обновлён N дней назад» и «подтвердить актуальность» раз в квартал. Устаревшие страницы не прячем — помечаем «deprecated» и даём ссылку на замену; внешние ссылки проверяет ночной линк-чекер и заводит тикеты. Визуально база предсказуема: одна сетка заголовков, одинаковые блоки «что вы узнаете», «шаги», «частые ошибки», «см. также». Если вы используете docs-as-code — договоритесь о структуре репозитория, линтерах Markdown, автосборке оглавлений и предпросмотре PR (каждый видит, что изменится, прежде чем «склеить»). И напоследок — «путь новичка»: отдельная индекс-страница «Начни здесь» с маршрутом онбординга и ссылками на «траектории» по ролям; это экономит часы онбординга и резко повышает шанс, что вики станет «рабочей памятью», а не «кладбищем PDF».
Метрики и процессы делают базу знаний устойчивой. Меряем не «количество страниц», а пользу: время до ответа (сколько минут уходит, чтобы найти инструкцию), долю вопросов, закрытых ссылкой на вики, глубину чтения и «петли обновления» (через сколько дней документ пересматривается). На еженедельном «борде метрик» — один экран: что искали, чего не нашли, какие страницы чаще всего спасали поддержку/онбординг, какие устарели. Процессы простые: 1) «из чата в вики» — полезные ответы превращаем в короткие гайды по шаблону, автор чата — со-автор документа; 2) «нет владельца — нет страницы» — при уходе владельца назначаем нового или архивируем; 3) «обновляешь — меняешь дату и пишешь пару строк в ченджлог»; 4) «ревью по пятницам» — редактор просматривает новые/помеченные страницы и чинит стиль/структуру. Для больших изменений — RFC: короткая заметка «что меняем в базе», окно комментариев, затем внедрение и ADR. Юридическая и безопасность — отдельный слой: профили доступа, красная маркировка чувствительных блоков, логи изменений, авто-бэкапы, офлайн-экспорт. Экономика — честная: считаем часы поддержки, сэкономленные за счёт «линка вместо созвона», и время онбординга до первой продуктивной задачи; по этим цифрам легко отбивается роль редактора/информационного архитектора. «Сигналы заботы» важны: быстрые шаблоны («создать гайд», «создать SOP», «создать ADR»), кнопка «сообщить о неточности», благодарности авторам в общем канале, «герои недели» за лучшие правки. Финальный принцип — документация — часть поставки: задача не «done», пока нет инструкции/ADR/обновлённого индекса. Тогда UOUO №10 превращает базу знаний из «боли и долга» в реальный продукт: люди находят ответы, процессы не зависят от «старожилов», а команда тратит время на работу, а не на вечные «а где ссылка?».