О структуре статьи
В статье существует стандартный порядок разделов контента. Каждая статья содержит обязательные элементы. Статьи также содержат условные элементы и необязательные элементы, описанные в проектировании или создании контента. Дополнительные сведения см. в приведенных ниже рекомендациях.
Titles
Заголовки полностью описывают, о чем речь идет страница, и что кто-то узнает, прочитав его.
Названия могут быть сложными. Используйте эти общие рекомендации для создания четких, полезных и описательных названий. Рекомендации по каждому типу контента в этой статье содержат более конкретные правила заголовка.
Заголовки для всех типов контента
- Заголовки четко описывают, о чем идет страница. Они являются описательными и конкретными.
- Использование: "Действия просмотра в редакторе рабочих процессов"
- Использование: "Пример настройки пространства кода"
- Избегайте: "Использование боковой панели редактора рабочих процессов"
- Избегайте: "Пример"
- Названия имеют жесткие ограничения на длину, чтобы их легко понять (и проще отрисовки на сайте):
- Названия категорий: 67 символов и
shortTitle
26 символов - Названия раздела карты: 63 символа и
shortTitle
29 символов - Названия статей: 80 символов, 60, если это возможно, и
shortTitle
30 символов, в идеале 20-25 символов
- Названия категорий: 67 символов и
- Заголовки используют вариант предложения.
- Использование: "Изменение сообщения фиксации"
- Избегайте: "Изменение сообщения фиксации"
- Заголовки согласованы между типом контента. Ознакомьтесь с определенными рекомендациями по каждому типу контента.
- Заголовки достаточно общие, чтобы масштабировать изменения продукта, отражать все содержимое статьи или включать содержимое в несколько продуктов.
- Использование: ""
- Избегайте: "Планы выставления счетов для учетных записей пользователей и организаций"
- Названия используют согласованную терминологию.
- Разработка и выполнение шаблонов в категории или на аналогичных темах.
- Названия используют терминологию самого продукта.
- Напишите заголовок и интро одновременно.
- Используйте интро для разработки идей, представленных в названии.
- Дополнительные сведения см. в руководстве по дополнительным сведениям .
- Если сложно придумать заголовок, рассмотрите тип контента. Иногда проблемы при выборе названия указывают на то, что другой тип контента лучше подходит.
- Подумайте о том, как название будет отображаться в результатах поиска для нескольких продуктов.
- Какие конкретные слова нам нужно включить в название или интро, чтобы люди не ошиблись его для содержимого о другом продукте?
- Подумайте о том, как название будет выглядеть в рабочей среде.
Выноска продукта
Используйте выноску продукта, если функция доступна только в определенных продуктах, и эта доступность не может быть передана только путем создания версий. Например, если функция доступна только для GHEC и GHES, можно использовать содержимое версии только для GHEC и GHES. Если функция доступна для Pro, Team, GHEC и GHES (но не бесплатно), используйте выноску продукта для передачи этой доступности.
Все выноски продукта хранятся в качестве повторно используемых gated-features
и добавляются в интерфейсный элемент YAML для соответствующих статей.
Как написать выноску продукта
- Выноски продуктов соответствуют строгому формату, четко определяя функцию и доступные в ней продукты.
- Выноски продуктов также включают ссылку на "продукты GitHub" и иногда к другой соответствующей статье.
- Примеры:
- [Имя компонента] доступно в [продуктах)]. Дополнительные сведения см. в разделе "Продукты GitHub".
- [Имя компонента] доступно в общедоступных репозиториях с [бесплатными продуктами], а также в общедоступных и частных репозиториях с [платными продуктами]. Дополнительные сведения см. в разделе "Продукты GitHub".
Примеры статей с выносками продуктов
Проверьте исходные файлы и gated-features
узнайте, как записывается исходное содержимое.
Вступление
В верхней части каждой страницы есть интро, который предоставляет контекст и задает ожидания, позволяя читателям быстро решить, относится ли страница к ним. Дополнительные сведения также отображаются в результатах поиска, чтобы предоставить контекстную информацию, чтобы помочь читателям выбрать результат.
Как написать интро
- Дополнительные сведения статьи — один к двум предложениям.
- Раздел карты и истро категории — это одно предложение длинное.
- Ссылки на API — это одно предложение длиной.
- Дополнительные сведения для страницы API должны определять функцию, чтобы кто-то знал, соответствует ли эта функция своим потребностям без чтения всей статьи.
- Инструкции содержат высокоуровневую сводку содержимого страницы, разрабатывая идею, представленную в заголовке с более подробной информацией.
- Используйте доступные синонимы слов в заголовке страницы, чтобы читатели понимали назначение статьи по-другому. Избегайте повторения слов из заголовка, когда это возможно.
- Интроты относительно вечнозеленые и высокоуровневые, поэтому они могут масштабироваться с последующими изменениями содержимого на странице без необходимости часто обновляться.
- Для поиска включите ключевое слово на тему страницы в интро.
- Если термин в интро имеет акроним, который мы будем использовать в других местах статьи, укажите акроним.
- Инструкции, как правило, не содержат разрешений для каких-либо задач, содержащихся в статье.
Инструкции разрешений
Каждая процедура содержит инструкцию разрешений, объясняющую роль, необходимую для выполнения действий, описанных в процедуре, что помогает людям понять, сможет ли они выполнить задачу.
Иногда это важно для упоминание необходимых разрешений в концептуальном содержимом, особенно в автономных концептуальных статьях. Не забудьте также включить инструкцию разрешений в связанные процедуры (или написать длинную статью, объединяющую все содержимое).
Как написать инструкцию разрешений
- Если один набор разрешений применяется ко всем процедурам в статье, используйте интерфейсные правила разрешений.
- Если статья содержит несколько процедур и различные разрешения применяются, добавьте отдельную инструкцию разрешений в каждом соответствующем заголовке перед каждой процедурой.
- Не включайте разрешения в подробное описание статьи.
- Роли существуют на разных уровнях. Обратитесь только к роли на том же уровне, что и действие. Например, для настройки защищенная ветвь требуется доступ администратора к репозиторию (роль уровня репозитория). Вы можете получить доступ администратора к репозиторию, будучи владелец организации (роль уровня организации), но роль уровня репозитория на самом деле управляет вашей способностью выполнять действия, поэтому это единственная роль, которая должна быть упоминание в инструкции разрешений.
- Язык для использования в инструкции разрешений:
- [РОЛЬ УЧЕТНОЙ ЗАПИСИ] может [ACTION].
- Люди с доступом [FEATURE ROLE] для [FEATURE] может [ACTION].
- ИЗБЕГАЙТЕ: [РОЛЬ УЧЕТНОЙ ЗАПИСИ] и пользователи с доступом [FEATURE] для [FEATURE] могут [ACTION].
Примеры инструкций разрешений
- Статья с одним оператором разрешений для нескольких процедур: Применение политик управления репозиториями в организации
Переключатель инструментов
Некоторые статьи содержат содержимое, которое зависит от того, какое средство используется для выполнения задачи, например GitHub CLI или GitHub Desktop. Для большинства содержимого одна и та же концептуальная или процедурная информация будет точной для нескольких инструментов. Однако если единственный способ очистить и точную информацию заключается в различении содержимого по инструменту, используйте переключатель инструментов. Не используйте переключатель инструментов только для отображения примеров на разных языках. Используйте переключатель инструментов только в том случае, если задачи или понятия изменяются на основе того, какое средство использует кто-то использует. Дополнительные сведения см. в разделе "Создание переключателей инструментов в статьях".
Оглавление
Таблицы содержимого создаются автоматически. Дополнительные сведения см. в разделе "Автогенерированные мини-toCs".
Концептуальное содержимое
Концептуальное содержимое помогает людям понять или узнать о теме. Дополнительные сведения см. в разделе "Концептуальный тип контента" в con режим палатки l.
Ссылка на содержимое
Ссылка на содержимое предоставляет структурированную информацию, связанную с активным использованием продукта или функции. Дополнительные сведения см. в разделе "Тип содержимого ссылок" в con режим палатки l.
Необходимые компоненты
Предварительные требования — это информация, которую необходимо знать, прежде чем продолжить процедуру, чтобы они могли подготовить все, что необходимо перед началом задачи.
Создание необходимых компонентов
- Напишите предварительные требования непосредственно перед нумерованными шагами процедуры.
- Для объяснения предварительных требований можно использовать список, предложение или абзац.
- Вы также можете использовать отдельный раздел предварительных требований, если:
- Сведения о предварительных требованиях очень важны и не должны быть пропущены.
- Существует несколько предварительных требований.
- Чтобы повторить или выделить важные сведения о потере данных или разрушительных действиях, можно также использовать предупреждение или выноску опасности для совместного использования необходимых компонентов.
Рекомендации по заголовку для предварительных требований
- При использовании отдельного раздела используйте заголовок с именем
Prerequisites
Примеры статей с разделами предварительных требований
Процедурное содержимое
Процедурное содержимое помогает людям выполнять задачи. Дополнительные сведения см. в разделе "Тип процедурного содержимого" в con режим палатки l.
Устранение неполадок содержимого
Устранение неполадок содержимого помогает людям избежать ошибок или работать с ней. Дополнительные сведения см. в разделе "Устранение неполадок с типом контента" в con режим палатки l.
Дополнительные материалы
Дополнительные разделы чтения содержат дополнительные целевые статьи, которые еще не включены в содержимое статьи. Используйте более подробное чтение разделов, когда они предоставляют реальное значение. "Формат дополнительных разделов чтения с помощью неупорядоченных списков. Сведения о записи ссылок см. в разделе "Руководство по стилю".
Заголовок и формат для дальнейшего чтения разделов
### Further reading
- "[Article title](article-URL)"
- [External resource title](external-resource-URL) in External Resource Name