Рекомендации по GitHub Docs

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

В этой статье

Сведения о документации по GitHub

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

Прежде чем вносить вклад в GitHub Docs, ознакомьтесь с принципами проектирования документации GitHubдокументации, основами и принципами проектирования контента:

Рекомендации по написанию документации по GitHub

Независимо от того, создаете ли вы новую статью или обновляете существующую, при написании данных GitHub Docsследует выполнить следующие рекомендации.

Выравнивание содержимого с учетом потребностей пользователя

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

Определение аудитории

  • Кто будет читать это содержимое?
  • Какое действие клиент пытается выполнить?

Определение основной цели

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

Определение типа контента

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

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

Структура содержимого для удобства чтения

Чтобы структурировать содержимое, используйте следующие рекомендации. При добавлении содержимого в существующую статью следуйте существующей структуре по возможности.

  • Укажите начальный контекст. Определите раздел и укажите его релевантность для читателя.
  • Структурируйте содержимое в логическом порядке по важности и релевантности. Поместите сведения в порядке приоритета и в том порядке, в который пользователи будут нуждаться.
  • Избегайте длинных предложений и абзацев.
    • Введите понятия по одному.
    • Используйте одну идею на абзац.
    • Используйте одну идею для каждого предложения.
  • Подчеркнуть наиболее важную информацию.
    • Начните каждое предложение или абзац с наиболее важными словами и выносами.
    • При объяснении концепции начните с вывода, а затем объясните его более подробно. (Иногда это называется "инвертированная пирамида".)
    • При объяснении сложной темы сначала представляйте читателям основные сведения и раскрывайте подробности далее в статье.
  • Используйте значимые подзаголовок. Упорядочение связанных абзацев в разделы. Присвойте каждому разделу подзаголовок, который является уникальным и точно описывает содержимое.
  • Рекомендуется использовать ссылки на страницы для более длинного содержимого. Это позволяет читателям переходить к областям интереса и пропускать содержимое, которое не имеет значения для них.

Запись для удобства чтения

Упростить чтение и понимание текста пользователями.

  • Используйте обычный язык. Используйте распространенные, повседневные слова и избегайте жаргона, когда это возможно. Термины, хорошо известные разработчикам, но не предполагают, что читатель знает подробности о том, как работает GitHub.
  • Используйте активный голос.
  • Будьте краткими.
    • Напишите предложения, которые являются простыми и краткими.
    • Избегайте сложных предложений, содержащих несколько понятий.
    • Синтаксический анализ ненужных сведений.

Дополнительные сведения см. в разделе "Голос и тон" в [AUTOTITLE и Руководство по стилю](/contributing/writing-for-github-docs/writing-content-to-be-translated).

Формат для проверки

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

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

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

  • Используйте выделение текста, например полужирный шрифт и гиперссылки , чтобы привлечь внимание к наиболее важным пунктам. Используйте выделение текста с разреженным образом. Не выделите более 10 % общего текста в статье.
  • Используйте элементы форматирования для разделения содержимого и создания пространства на странице. Например:
    • Маркированные списки (с необязательными подзаголовоками запуска)
    • Нумерованные списки
    • Оповещения
    • Таблицы
    • Визуальные элементы
    • Блоки кода и заметки кода

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