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