Вы только что обновили README, добавили схемы в Confluence и закрыли самые частые вопросы. Но через пару дней кто-то из коллег всё равно пишет: «А как правильно?» Обычно после такого предлагают лучше документировать — и начинают добавлять страницы. Есть другое решение.
Вы только что обновили README, добавили схемы в Confluence и закрыли самые частые вопросы. Но через пару дней кто-то из коллег всё равно пишет: «А как правильно?» Обычно после такого предлагают лучше документировать — и начинают добавлять страницы. Есть другое решение.
В статье есть ссылки партнеров. Это значит, что если вы что-то покупаете с нашей помощью — вы также поддерживаете dev.by. (Вот другой способ).
При этом редакция и авторы независимы в выборе темы, концепции материала, фокуса описания, подхода к услугам или товарам. Прежде чем что-то советовать, мы много читаем и смотрим по теме, говорим с экспертами.
Редакция может выражать свое мнение и пробовать всё на себе.
Если рекомендательный материал обновляется, мы указываем, что и когда поменялось, в самом начале.
Начинать стоит с того самого часто повторяющегося вопроса. Сделайте под него страницу с ясным следующим действием, поставьте ссылку там, где возникает задача, и назначьте владельца актуальности. А если эта цепочка не сработает, новые страницы вряд ли изменят ситуацию.
Ниже — компактный гайд о том, как разобрать одну такую страницу.
Допустим, коллега пытается подключить OAuth и спрашивает, куда положить параметры и почему API возвращает 403. В этот момент человеку не нужна вся история сервиса. Требуется лишь ответ, после которого можно продолжить работу: какие собрать данные, какой запрос отправить, где посмотреть ошибку.
В гайде Supered это сравнивают с разницей между книгой рецептов и карточкой у плиты. Обе могут описывать один процесс, но карточка нужна именно тогда, когда вы уже готовите.
Неплохая идея решения Герберта Саймона — bounded rationality и satisficing — предлагает поставить один практический вопрос: а не получиться ли поиск ответа дороже, чем короткий вопрос коллеге?
OAuth можно объяснять по-разному. Новичку нужен tutorial: пройти путь от первого шага до работающего подключения. Разработчику, который уже знает систему, — how-to с конкретной последовательностью. Когда запрос уже собран, пригодится reference с параметрами и форматами. А решение о схеме авторизации требует explanation: почему всё устроено так.
Эти четыре формы различает Diátaxis. Важно выбрать одну главную роль для страницы. Если How-to одновременно становится историей продукта, справочником параметров и архитектурным эссе, человек с ошибкой 403 начинает искать нужный кусок среди чужих задач.
Заголовок помогает это предотвратить. «Подключить OAuth» обещает действие, а вот «Аутентификация» пока ничего не обещает. Такой переход от названия endpoint к задаче разбирает Chatiant. Модель Five Moments of Need добавляет полезный вопрос: человек сейчас учится, применяет уже известное, чинит проблему или осваивает изменение? От ответа зависит, какую страницу он сможет использовать сразу.
Похожая практическая идея у технического минимализма Джона Кэрролла: материал должен помогать действию, а не заставлять сначала пройти через всё, что автор знает о системе.
Когда задача и тип страницы ясны, остаётся путь к ней. Ссылка на How-to может появиться в шаблоне Jira при смене статуса, в CRM во время оформления сделки или в интерфейсе продукта рядом с ошибкой. Для API часть reference удобно публиковать из спецификации OpenAPI или Swagger.
Обновление тоже лучше сделать видимой работой. Подход Docs-as-Code связывает документацию с изменениями функциональности: Git, review и историю правок — пример такого процесса описывает Eleks. Тогда изменение OAuth не остаётся только в задаче разработчика и у страницы появляется шанс обновиться в том же цикле.
Автоматические проверки поддерживают этот цикл: Vale следит за терминологией и стилем, markdownlint — за Markdown-разметкой, отдельный инструмент проверяет внешние URL. Но нужную страницу и её сценарий всё равно определяет человек, который знает, что изменилось в работе команды.
После публикации не обязательно начинать с подсчёта новых документов. Посмотрите, что произошло с тем самым вопросом: исчезли ли поисковые запросы без результата, дошёл ли человек от страницы до следующего шага, стало ли меньше повторяющихся обращений. Руководство Fluid Topics называет такие сигналы поиском без результатов, пользовательским путём и case deflection.
У страницы должен быть конкретный владелец: человек, который узнаёт об изменении процесса и обновляет объяснение. В Supered это называют named owner. Для OAuth-страницы таким триггером может быть новая схема авторизации, изменённый параметр или новый сценарий ошибки.
Получается короткий рабочий цикл:
Если вы уже нашли такой вопрос, но не знаете, как превратить его в ясную техническую инструкцию, пригодиться курс Technical Writing for Software Developers на Coursera.
Документация начинает работать не после очередного расширения базы, а в момент, когда человек с конкретной задачей быстро находит в ней следующий шаг, которому можно доверять.
Релоцировались? Теперь вы можете комментировать без верификации аккаунта.