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