Для получения конкретной информации обращаются к справочному контенту. Это информация, которую можно быстро проверить, то есть меньше внимания уделяется предложениям и абзацам.
Ссылка включает информацию, которую лучше всего представить в таблицах, списках или других структурированных форматах. Мы можем рассматривать референс как включение автосгенерированного контента конвейера и другого контента, который потенциально можно автоматизировать.
Справочное содержание появляется в справочных статьях и разделах в других статьях.
- Некоторые крупные темы могут требовать собственной справочной статьи, особенно если там много ссылочного контента, например, для синтаксиса поиска или YAML-синтаксиса в GitHub Actions.
- Для небольших объёмов контента или более конкретной информации, например, списка поддерживаемых языков или аппаратных требований, используйте разделы с ссылками в контексте процедурных или концептуальных статей.
Как писать справочный контент
Для шаблона справочного содержания см. Шаблоны.
- Напишите предложение или целый концептуальный раздел, чтобы представить ссылочное содержание.
- Представляйте референсный материал чётко и последовательно.
- Для темы с одним элементом, чтобы объяснить, используйте список.
- Для темы с несколькими элементами, чтобы объяснить, используйте таблицу.
- Для более длинного ссылочного содержимого, например синтаксис YAML для рабочих процессов, последовательно используйте заголовки.
- Заголовки H2 для каждого отдельного раздела.
- Заголовки H3 для подразделов, например примеры.
- Пример: Синтаксис рабочего процесса для GitHub Actions
Заголовки для ссылочной информации
- Ссылки на статьи или заголовки референтных разделов четко описывают содержимое раздела и обычно начинаются с существительных.
- Заголовки включают достаточно информации, чтобы быть доступными для начинающих пользователей и полностью описывать содержимое каждого раздела.
- Названия избежать стека существительных — используйте препозиции для разбиения длинных строк существительных.
- Короткие названия должны быть одним словом или короткой именной фразой. Пример: «Модели ИИ».
Примеры справочного контента
- Справочные статьи * События журнала аудита для организации * Возможности ролей на предприятии * Конечные точки REST API для выставления счетов в документации по REST API * Изменения в документации по API GraphQL
- Разделы с ссылками в других статьях
- "Поддерживаемые языки" в GitHub Mobile
- "Рекомендации по оборудованию" в Установка GitHub Enterprise Server на AWS