Содержимое статьи GitHub Docs

О структуре статьи

В статье существует стандартный порядок разделов контента. Каждая статья содержит обязательные элементы. Статьи также содержат условные элементы и необязательные элементы, описанные в проектировании или создании контента. Дополнительные сведения см. в приведенных ниже рекомендациях.

Titles

Заголовки полностью описывают, о чем речь идет страница, и что кто-то узнает, прочитав его.

Названия могут быть сложными. Используйте эти общие рекомендации для создания четких, полезных и описательных названий. Рекомендации по каждому типу контента в этой статье содержат более конкретные правила заголовка.

Заголовки для всех типов контента

• Заголовки четко описывают, о чем идет страница. Они являются описательными и конкретными.
  • Использование: "Действия просмотра в редакторе рабочих процессов"
  • Использование: "Пример настройки пространства кода"
  • Избегайте: "Использование боковой панели редактора рабочих процессов"
  • Избегайте: "Пример"
• Названия имеют жесткие ограничения на длину, чтобы их легко понять (и проще отрисовки на сайте):
  • Названия категорий: 67 символов и shortTitle 26 символов
  • Названия раздела карты: 63 символа и shortTitle 29 символов
  • Названия статей: 80 символов, 60, если это возможно, и shortTitle 30 символов, в идеале 20-25 символов
• Заголовки используют вариант предложения.
  • Использование: "Изменение сообщения фиксации"
  • Избегайте: "Изменение сообщения фиксации"
• Заголовки согласованы между типом контента. Ознакомьтесь с определенными рекомендациями по каждому типу контента.
• Заголовки достаточно общие, чтобы масштабировать изменения продукта, отражать все содержимое статьи или включать содержимое в несколько продуктов.
  • Использование: ""
  • Избегайте: "Планы выставления счетов для учетных записей пользователей и организаций"
• Названия используют согласованную терминологию.
  • Разработка и выполнение шаблонов в категории или на аналогичных темах.
• Названия используют терминологию самого продукта.
• Напишите заголовок и интро одновременно.
  • Используйте интро для разработки идей, представленных в названии.
  • Дополнительные сведения см. в руководстве по дополнительным сведениям .
• Если сложно придумать заголовок, рассмотрите тип контента. Иногда проблемы при выборе названия указывают на то, что другой тип контента лучше подходит.
• Подумайте о том, как название будет отображаться в результатах поиска для нескольких продуктов.
  • Какие конкретные слова нам нужно включить в название или интро, чтобы люди не ошиблись его для содержимого о другом продукте?
• Подумайте о том, как название будет выглядеть в рабочей среде.

Вступление

В верхней части каждой страницы есть интро, который предоставляет контекст и задает ожидания, позволяя читателям быстро решить, относится ли страница к ним. Дополнительные сведения также отображаются в результатах поиска, чтобы предоставить контекстную информацию, чтобы помочь читателям выбрать результат.

Как написать интро

• Дополнительные сведения статьи — один к двум предложениям.
• Раздел карты и истро категории — это одно предложение длинное.
• Ссылки на API — это одно предложение длиной.
  • Дополнительные сведения для страницы API должны определять функцию, чтобы кто-то знал, соответствует ли эта функция своим потребностям без чтения всей статьи.
• Инструкции содержат высокоуровневую сводку содержимого страницы, разрабатывая идею, представленную в заголовке с более подробной информацией.
  • Используйте доступные синонимы слов в заголовке страницы, чтобы читатели понимали назначение статьи по-другому. Избегайте повторения слов из заголовка, когда это возможно.
• Интроты относительно вечнозеленые и высокоуровневые, поэтому они могут масштабироваться с последующими изменениями содержимого на странице без необходимости часто обновляться.
• Для поиска включите ключевые слова на тему страницы в интро.
• Если термин в интро имеет акроним, который мы будем использовать в других местах статьи, укажите акроним.
• Инструкции, как правило, не содержат разрешений для каких-либо задач, содержащихся в статье.

Инструкции разрешений

Каждая процедура содержит инструкцию разрешений, объясняющую роль, необходимую для выполнения действий, описанных в процедуре, что помогает людям понять, сможет ли они выполнить задачу.

Иногда важно упомянуть необходимые разрешения в концептуальном содержимом, особенно в автономных концептуальных статьях. Не забудьте также включить инструкцию разрешений в связанные процедуры (или написать длинную статью, объединяющую все содержимое).

Как написать инструкцию разрешений

• Если один набор разрешений применяется ко всем процедурам в статье, используйте интерфейсные правила разрешений.
• Если статья содержит несколько процедур и различные разрешения применяются, добавьте отдельную инструкцию разрешений в каждом соответствующем заголовке перед каждой процедурой.
• Не включайте разрешения в подробное описание статьи.
• Роли существуют на разных уровнях. Обратитесь только к роли на том же уровне, что и действие. Например, для настройки защищенная ветвь требуется доступ администратора к репозиторию (роль уровня репозитория). Вы можете получить доступ администратора к репозиторию, будучи владелец организации (роль уровня организации), но роль уровня репозитория на самом деле управляет вашей способностью выполнять действия, поэтому это единственная роль, которую следует упомянуть в инструкции разрешений.
• Язык для использования в инструкции разрешений:
  • [РОЛЬ УЧЕТНОЙ ЗАПИСИ] может [ACTION].
  • Пользователи с доступом [FEATURE ROLE] для [FEATURE] могут [ACTION].
  • ИЗБЕГАЙТЕ: [РОЛЬ УЧЕТНОЙ ЗАПИСИ] и пользователи с доступом [FEATURE] для [FEATURE] могут [ACTION].

Примеры инструкций разрешений

• Статья с одним оператором разрешений для нескольких процедур: Применение политик управления репозиториями в организации

Выноска продукта

Используйте выноску продукта, если функция доступна только в определенных продуктах, и эта доступность не может быть передана только путем создания версий. Например, если функция доступна только для GHEC и GHES, можно использовать содержимое версии только для GHEC и GHES. Если функция доступна для Pro, Team, GHEC и GHES (но не бесплатно), используйте выноску продукта для передачи этой доступности.

Все выноски продукта хранятся в качестве повторно используемых gated-features и добавляются в интерфейсный элемент YAML для соответствующих статей.

Как написать выноску продукта

• Выноски продуктов соответствуют строгому формату, четко определяя функцию и доступные в ней продукты.
• Выноски продуктов также включают ссылку на "продукты GitHub" и иногда к другой соответствующей статье.
• Примеры:
  • [Имя компонента] доступно в [продуктах)]. Дополнительные сведения см. в разделе "Продукты GitHub".
  • [Имя компонента] доступно в общедоступных репозиториях с [бесплатными продуктами], а также в общедоступных и частных репозиториях с [платными продуктами]. Дополнительные сведения см. в разделе "Продукты GitHub".

Примеры статей с выносками продуктов

Проверьте исходные файлы и gated-features узнайте, как записывается исходное содержимое.

• Управление правилом защиты ветвей

Переключатель инструментов

Некоторые статьи содержат содержимое, которое зависит от того, какое средство используется для выполнения задачи, например GitHub CLI или GitHub Desktop. Для большинства содержимого одна и та же концептуальная или процедурная информация будет точной для нескольких инструментов. Однако если единственный способ очистить и точную информацию заключается в различении содержимого по инструменту, используйте переключатель инструментов. Не используйте переключатель инструментов только для отображения примеров на разных языках. Используйте переключатель инструментов только в том случае, если задачи или понятия изменяются на основе того, какое средство использует кто-то использует. Дополнительные сведения см. в разделе "Создание переключателей инструментов в статьях".

Оглавление

Таблицы содержимого создаются автоматически. Дополнительные сведения см. в разделе "Автогенерированные мини-toCs".

Концептуальное содержимое

Концептуальное содержимое помогает людям понять или узнать о теме. Дополнительные сведения см. в разделе "Концептуальный тип контента" в con режим палатки l.

Ссылка на содержимое

Ссылка на содержимое предоставляет структурированную информацию, связанную с активным использованием продукта или функции. Дополнительные сведения см. в разделе "Тип содержимого ссылок" в con режим палатки l.

Необходимые компоненты

Предварительные требования — это информация, которую необходимо знать, прежде чем продолжить процедуру, чтобы они могли подготовить все, что необходимо перед началом задачи.

Создание необходимых компонентов

• Напишите предварительные требования непосредственно перед нумерованными шагами процедуры.
• Для объяснения предварительных требований можно использовать список, предложение или абзац.
• Вы также можете использовать отдельный раздел предварительных требований, если:
  • Сведения о предварительных требованиях очень важны и не должны быть пропущены.
  • Существует несколько предварительных требований.
• Чтобы повторить или выделить важные сведения о потере данных или разрушительных действиях, можно также использовать предупреждение или выноску опасности для совместного использования необходимых компонентов.

Рекомендации по заголовку для предварительных требований

• При использовании отдельного раздела используйте заголовок с именем Prerequisites

Примеры статей с разделами предварительных требований

• Установка сервера GitHub Enterprise в AWS
• Включение изоляции поддомена

Процедурное содержимое

Процедурное содержимое помогает людям выполнять задачи. Дополнительные сведения см. в разделе "Тип процедурного содержимого" в con режим палатки l.

Устранение неполадок содержимого

Устранение неполадок содержимого помогает людям избежать ошибок или работать с ней. Дополнительные сведения см. в разделе "Устранение неполадок с типом контента" в con режим палатки l.

Следующие шаги

Когда статья описывает один шаг в более крупном процессе или имеет логический следующий шаг, который большинство людей хотят сделать, включите следующий раздел. Вы можете связать людей с статьями или другими ресурсами GitHub.

Примеры следующих разделов

## Next steps

- You can monitor self-hosted runners and troubleshoot common issues. See "Monitoring and troubleshooting self hosted runners."

- GitHub recommends that you review security considerations for self-hosted runner machines. See "Security hardening for GitHub Actions."

В этом примере из раздела "Начало работы со средствами выполнения тестов локального размещения для вашего предприятия" в следующем разделе содержатся ссылки на процедуры, которые потребуется выполнить после начала использования функции, описанной в статье.

## Next steps

After your enterprise account is created, we recommend learning more about how enterprise accounts work and configuring settings and policies. Follow the "Get started with your enterprise account" learning path.

В этом примере из "Создание учетной записи предприятия" следующий шаг ссылается на то, где большинство пользователей, которые только что закончили создание корпоративной учетной записи, хотели бы перейти дальше.

Дополнительные материалы

Если существуют дополнительные статьи, которые помогают людям выполнять свою задачу или учиться использовать раздел, описанный в текущей статье, включите их в дополнительный раздел чтения. Только ссылки на статьи, к которым еще не были связаны в содержимом статьи.

Только ссылки, которые помогают людям с задачей или темой. Лучше сосредоточиться и предоставить людям ценные ресурсы, чем предложить им каждую возможную ссылку.

Форматирование дополнительных разделов чтения с помощью неупорядоченных списков. Сведения о записи ссылок см. в разделе "Руководство по стилю".

Заголовок и формат для дальнейшего чтения разделов

## Further reading
- "[Article title](article-URL)"
- [External resource title](external-resource-URL) in External Resource Name