Наш 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 использует пользователь.
- Примеры
Категория
Категории упорядочены вокруг функции или дискретного набора задач в наборе документов верхнего уровня, выровненных с темами продукта. Тема категории достаточно узкой, чтобы ее содержимое было управляемым и не увеличивается слишком большой для использования. Некоторые категории отображаются на домашней странице.
- Категории часто начинаются с малого и растут вместе с продуктом.
- Категории могут содержать разделы карты для подразделов содержимого вокруг более конкретных путешествий пользователей или задач.
- Используйте длинные процедурные статьи для группирования связанных фрагментов содержимого и поддержания статей в категории упрощено.
- Если категории имеют более десяти статей, рассмотрите возможность разбиения содержимого в разделы карты или дополнительные категории.
- Категории могут содержать несколько разделов карт или статей.
Названия категорий
- На основе задач (начинается с герунда).
- Описывает цель или цель использования функции или продукта.
- Общий или высокий уровень, чтобы масштабироваться с помощью будущих улучшений продукта.
- Названия категорий должны иметь 67 символов или короче и иметь
shortTitleменее 27 символов. - Примеры
Введение для категорий
Все категории имеют вводные сведения. Входящие должны быть одним предложением длинного и общего или достаточно высокого уровня, чтобы масштабироваться с последующими изменениями продукта. Если вы значительно измените структуру категории, ознакомьтесь со своими подробными сведениями о необходимых обновлениях.
Раздел карты
Разделы карты представляют раздел категории, группирование статей в категории вокруг более конкретных рабочих процессов или тем, которые являются частью более крупной задачи категории.
Разделы карты содержат по крайней мере две статьи. Если разделы карты содержат более восьми статей, рекомендуется рассмотреть возможность нарушения содержимого в более конкретных разделах карты.
Как правило, не используйте раздел карты в разделе карты, если это не лучший способ удовлетворить потребности конкретного пользователя.
Заголовки для разделов карт
- На основе задач (начинается с герунда).
- Описывает более конкретную задачу в более крупном рабочем процессе категории, в которую она находится.
- Общий или высокий уровень, чтобы масштабироваться с будущими дополнениями к продукту.
- Названия раздела карты должны быть 63 символами или короче и иметь
shortTitleменее 30 символов. - Примеры
Дополнительные сведения для разделов карт
Все разделы карты содержат вводные сведения. Входящие должны быть одним предложением длинного и общего или достаточно высокого уровня, чтобы масштабироваться с последующими изменениями продукта. Если вы добавляете или удаляете статьи в разделе карты, ознакомьтесь со своими дополнительными сведениями о необходимых обновлениях.
Статья
Статья — это основная единица содержимого для GitHub Docs– при использовании нескольких типов контента они публикуются как статьи. Каждый тип контента имеет свою собственную цель, формат и структуру, но мы используем стандартные элементы в каждом типе статьи, например интро, для обеспечения согласованного взаимодействия с пользователем.
Порядок содержимого
Мы прогнозируем содержимое в категориях, разделах карты и статьях. От наиболее широкой применимости к наиболее конкретным, узким или расширенным сведениям в следующем порядке:
- Концептуальное содержимое
- Ссылка на содержимое
- Процедурное содержимое для включения компонента или параметра
- Процедурное содержимое для использования функции
- Процедурное содержимое для управления компонентом или параметром
- Процедурное содержимое при отключении компонента или параметра
- Процедурное содержимое для разрушительных действий (например, удаление)
- Сведения об устранении неполадок
Повторное использовать содержимое
Для многократного использования и строк переменных используются те же фрагменты содержимого, такие как процедурный шаг или концептуальный абзац, в нескольких местах. Как правило, мы не будем повторно использовать большие разделы статей без определенной причины. Если весь раздел статьи может быть актуальным в нескольких статьях, ознакомьтесь с целью обоих. Есть ли возможность создать одну, длинную статью? Обратитесь к con режим палатки ls, чтобы уточнить лучший постоянный дом для информации, и связать его с другой статьей.