Статьи с меткой: Текст
Доступность в документации не заканчивается навигацией и контрастом. Примеры кода, JSON-ответы, справочные таблицы и поясняющие иллюстрации тоже должны оставаться понятными, считываемыми и полезными без опоры только на цвет.
Технически валидный запрос ещё не хороший пример. Выбирайте примеры, которые раскрывают модель API, используют реалистичные значения и помогают разработчику предсказать следующий шаг. Пример, автоматически собранный из схемы, может быть синтаксически правильным и при этом ничему не учить.
Хорошая документация по аутентификации описывает весь жизненный цикл учётных данных: получение доступа, передачу, ротацию и диагностику ошибок. До первого HTTP-запроса объясните prerequisites, роли, окружения и способ выдачи учётных данных.
Полезный список чтения сегодня — не полка классики. Сравниваем актуальные гайды Microsoft, Google, GitHub и IBM, используем Diátaxis для проверки структуры и превращаем каждое чтение в конкретное упражнение над документацией.
Читать о документации полезно, но навык быстрее растёт через повторяемые небольшие упражнения на исследование, перестройку структуры, редактуру и проверку с понятной обратной связью. «Стать лучше в техническом письме» слишком широко.
Диаграммы, заданные текстом, удобно сопровождать и проверять, но только если визуальная задача соответствует тому, что выбранная нотация умеет выражать понятно. Диаграммы как код хорошо подходят для потоков, состояний, зависимостей и последовательностей, где главное — связи.
Справочник ошибок полезен только тогда, когда помогает определить условие, понять ответ и выбрать безопасное следующее действие. Описывайте условие возникновения ошибки, а не только код и сообщение.
Хорошая API-документация сочетает машиночитаемый контракт, человеческие объяснения, запускаемые примеры и явное описание ошибок. У REST API-документации сразу две аудитории: машины и люди.
Короткие повторяемые упражнения тренируют диагностику: поиск неоднозначности, пропущенных условий, слабой структуры и лишних слов в реальной документации. Тренируйте один дефект за раз: prerequisites, расплывчатые глаголы, терминологию, длинные предложения или отсутствие результата.
Markdown остаётся простым только тогда, когда команда заранее договорилась о структуре, метаданных и расширениях, пока тысячи файлов не сделали каждое исключение вечным. Заранее стандартизируйте имена файлов, frontmatter, заголовки, изображения и внутренние ссылки.
Описание OpenAPI позволяет генерировать точную структуру справочника, но разработчику всё равно нужны концепции, сценарии, аутентификация, примеры и восстановление после ошибок — то, чего одна схема объяснить не может. OpenAPI отлично описывает операции, параметры, структуры запросов и ответов, статус-коды и повторно используемые схемы.
Заметки о выпуске становятся полезными, когда объясняют последствия, решения и нужные действия, а не повторяют внутренний список задач. Внутренний changelog не является сообщением пользователю: техническое изменение нужно перевести в последствия.