Skip to main content

Эта версия GitHub Enterprise Server была прекращена 2024-03-26. Исправления выпускаться не будут даже при критических проблемах безопасности. Для повышения производительности, повышения безопасности и новых функций выполните обновление до последней версии GitHub Enterprise Server. Чтобы получить справку по обновлению, обратитесь в службу поддержки GitHub Enterprise.

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

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

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

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

Снимок экрана: статья с заголовком, интро, разрешениями, выноской продукта, концептуальными разделами, процедурным разделом и оглавлением.

Titles

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

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

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

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

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

Используйте выноску продукта, если функция доступна только в определенных продуктах, и эта доступность не может быть передана только путем создания версий. Например, если функция доступна только для 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