О con режим палатки l

Con режим палатки l описывает структуру и типы содержимого, которое мы публикуем.

В этой статье

Наш con режим палатки l объясняет назначение каждого типа контента, который мы создаем в GitHub Docs, и что следует включить при написании или обновлении статьи. Мы используем con режим палатки l, чтобы обеспечить согласованное, четкое и комплексное взаимодействие с информацией, которую люди должны достичь своих целей с GitHub.

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

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

Структура содержимого

Документация организована на нескольких уровнях иерархии на нашем сайте.

  • Набор документов верхнего уровня
    • Категории
      • Разделы карты
        • Статьи

Содержимое домашней страницы

Домашняя страница GitHub Docs, docs.github.com, выделяет наиболее важные темы, которые люди хотят найти. Мы ограничиваем количество наборов документов на домашней странице, чтобы пользователи могли найти информацию, и домашняя страница не становится переполненной и сложной для поиска.

Домашняя страница содержит все наборы документов верхнего уровня и некоторые категории. Содержимое домашней страницы организовано вокруг принципов и практики GitHub . Например, группа CI/CD и DevOps включает наборы документов верхнего уровня для GitHub Actions, GitHub Packagesи GitHub Pages.

Добавление набора документов на домашнюю страницу

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

Если создается новый набор документов верхнего уровня, он добавляется на домашнюю страницу.

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

Например, в группе "Безопасность" на домашней странице в дополнение к набору документов верхнего уровня "Безопасность кода", "Безопасность цепочки поставок", "Советы по безопасности", "[Dependabot", "Code scanning](/code-security/code-scanning)" и "Secret scanning"Категории включены, поскольку каждая из этих категорий является точкой входа в GitHub продуктов и функций. Обзор безопасности не включен на домашнюю страницу, так как он предоставляет дополнительные сведения об использовании продуктов безопасности кода и не является введением в продукт или функцию.

Набор документов верхнего уровня

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

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

Заголовки для наборов документов верхнего уровня

Категория

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

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

Названия категорий

Введение для категорий

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

Раздел карты

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

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

Заголовки для разделов карт

Дополнительные сведения для разделов карт

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

Статья

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

Порядок содержимого

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

  • Концептуальное содержимое
  • Ссылка на содержимое
  • Процедурное содержимое для включения компонента или параметра
  • Процедурное содержимое для использования функции
  • Процедурное содержимое для управления компонентом или параметром
  • Процедурное содержимое при отключении компонента или параметра
  • Процедурное содержимое для разрушительных действий (например, удаление)
  • Сведения об устранении неполадок

Повторное использовать содержимое

Для многократного использования и строк переменных используются те же фрагменты содержимого, такие как процедурный шаг или концептуальный абзац, в нескольких местах. Как правило, мы не будем повторно использовать большие разделы статей без определенной причины. Если весь раздел статьи может быть актуальным в нескольких статьях, ознакомьтесь с целью обоих. Есть ли возможность создать одну, длинную статью? Обратитесь к con режим палатки ls, чтобы уточнить лучший постоянный дом для информации, и связать его с другой статьей.