Статьи с меткой: Качество
Генеративный текст может звучать завершённо и при этом выдумывать значения по умолчанию, гарантии или источники. Стройте проверку вокруг авторитетных данных, исполняемых примеров и явной неопределённости. Самая опасная ошибка ИИ в документации обычно не грамматическая.
Технически валидный запрос ещё не хороший пример. Выбирайте примеры, которые раскрывают модель API, используют реалистичные значения и помогают разработчику предсказать следующий шаг. Пример, автоматически собранный из схемы, может быть синтаксически правильным и при этом ничему не учить.
Поиск по документации нужно выбирать и настраивать вокруг запросов, которые пользователь не может разрешить, а не вокруг длинного списка функций поставщика. Поиск особенно полезен, когда читатель знает термин или симптом, но не знает, где лежит информация.
Практический способ отделить безобидные старые страницы от долга документации, который приводит к обращениям в поддержку, ошибкам и рискам релиза. Возраст страницы сам по себе не создаёт долг; долг проявляется в пользовательских ошибках и стоимости сопровождения.
Относитесь к документации как к сборочному артефакту: проверяйте структуру, ссылки, примеры и правила публикации до того, как изменения увидят читатели. CI не решит, полезно ли объяснение читателю, но способен отсеять множество предсказуемых дефектов до того, как на них потратит время человек.
Как измерять, помогает ли документация пользователям выполнять задачи и команде поддерживать знания, а не только считать открытия страниц. Трафик — контекст, а не успех: популярная страница может быть популярной именно потому, что она непонятна.
Процесс ревью должен показывать ответственность, сокращать ожидание и разделять фактическую, редакторскую и продуктовую проверку. Ревью документации ломается, когда непонятно, кто должен действовать дальше.
Справочник ошибок полезен только тогда, когда помогает определить условие, понять ответ и выбрать безопасное следующее действие. Описывайте условие возникновения ошибки, а не только код и сообщение.
Хорошая API-документация сочетает машиночитаемый контракт, человеческие объяснения, запускаемые примеры и явное описание ошибок. У REST API-документации сразу две аудитории: машины и люди.
Глоссарий становится полезным, когда управляет решениями в продукте, интерфейсе и документации, а не просто собирает слова. Полезная терминологическая запись отвечает не только на вопрос «что означает слово?».
Хороший процесс найма показывает, как кандидат понимает пользователя, проверяет факты и улучшает информацию, а не награждает за многочасовое бесплатное тестовое. Проверяйте ту работу, которая действительно нужна роли, а не грамматические головоломки и редкие термины.
Структура, удобная на пятидесяти страницах, может развалиться на пятистах. Стройте навигацию вокруг задач пользователя, типов контента и устойчивых понятий, а не вокруг оргструктуры компании. Небольшой набор документации способен пережить почти любую навигацию.