Процессы, ревью, информационная архитектура и практическая работа с документацией.
Docs-as-Code — это не требование посадить всех техписов в IDE. Разбираем нормальный путь: где хранить исходники, как редактировать их прямо в браузере, какие проверки отдавать автоматике, как устроить ревью и как измерить реальную экономию времени.
Практический способ отделить безобидные старые страницы от долга документации, который приводит к обращениям в поддержку, ошибкам и рискам релиза. Возраст страницы сам по себе не создаёт долг; долг проявляется в пользовательских ошибках и стоимости сопровождения.
Как определить, кто принимает решения, проверяет и сопровождает каждый раздел документации, не создавая матрицу, которую никто не хочет обновлять. Владение означает ответственность за область, а не обязанность написать каждое предложение.
Процесс ревью должен показывать ответственность, сокращать ожидание и разделять фактическую, редакторскую и продуктовую проверку. Ревью документации ломается, когда непонятно, кто должен действовать дальше.
Структура, удобная на пятидесяти страницах, может развалиться на пятистах. Стройте навигацию вокруг задач пользователя, типов контента и устойчивых понятий, а не вокруг оргструктуры компании. Небольшой набор документации способен пережить почти любую навигацию.
Заметки о выпуске становятся полезными, когда объясняют последствия, решения и нужные действия, а не повторяют внутренний список задач. Внутренний changelog не является сообщением пользователю: техническое изменение нужно перевести в последствия.