Сведения о документации по GitHub
В GitHubмы стремимся создать документацию, которая является точной, ценной, инклюзивной, доступной и удобной для использования.
Прежде чем вносить вклад в GitHub Docs, ознакомьтесь с принципами разработки документации и содержимого GitHub:
Рекомендации по написанию документации по GitHub
Независимо от того, создаете ли вы новую статью или обновляете существующую, при написании данных GitHub Docsследует выполнить следующие рекомендации.
- Выравнивание содержимого с учетом потребностей пользователя
- Структура содержимого для удобства чтения
- Запись для удобства чтения
- Формат для проверки
Выравнивание содержимого с учетом потребностей пользователя
Прежде чем начать, важно понять, кто вы пишете, какие их цели являются, основные задачи или понятия, которые будет решать статья, и какой тип содержимого следует писать.
Определение аудитории
- Кто будет читать это содержимое?
- Какое действие клиент пытается выполнить?
Определение основной цели
- Что кто-то должен иметь возможность делать или понимать после прочтения этой статьи? Выберите одну или две задачи или понятия, которые будут обсуждаться содержимым.
- Если существуют дополнительные задачи, понятия или сведения, которые не являются важными, рассмотрите возможность их размещения ниже в статье, перемещении в другую статью или опущены полностью.
Определение типа контента
Определите тип содержимого, который вы будете писать, на основе целевой аудитории и основной цели содержимого. GitHub Docs используйте следующие типы контента:
- Концептуальное содержимое
- Ссылка на содержимое
- Процедурное содержимое
- Устранение неполадок содержимого
- Краткое руководство
- Руководство
Например, используйте концептуальный тип контента, чтобы помочь читателям понять основы функции или раздела и как они могут помочь им достичь своих целей. Используйте процедурный тип контента, чтобы помочь людям выполнить определенную задачу с начала до конца.
Структура содержимого для удобства чтения
Чтобы структурировать содержимое, используйте следующие рекомендации. При добавлении содержимого в существующую статью следуйте существующей структуре по возможности.
- Укажите начальный контекст. Определите раздел и укажите его релевантность для читателя.
- Структурируйте содержимое в логическом порядке по важности и релевантности. Поместите сведения в порядке приоритета и в том порядке, в который пользователи будут нуждаться.
- Избегайте длинных предложений и абзацев.
- Введите понятия по одному.
- Используйте одну идею на абзац.
- Используйте одну идею для каждого предложения.
- Подчеркнуть наиболее важную информацию.
- Начните каждое предложение или абзац с наиболее важными словами и выносами.
- При объяснении концепции начните с вывода, а затем объясните его более подробно. (Иногда это называется "инвертированная пирамида".)
- При объяснении сложной темы сначала представляйте читателям основные сведения и раскрывайте подробности далее в статье.
- Используйте значимые подзаголовок. Упорядочение связанных абзацев в разделы. Присвойте каждому разделу подзаголовок, который является уникальным и точно описывает содержимое.
- Рекомендуется использовать ссылки на страницы для более длинного содержимого. Это позволяет читателям переходить к областям интереса и пропускать содержимое, которое не имеет значения для них.
Запись для удобства чтения
Упростить чтение и понимание текста пользователями.
- Используйте обычный язык. Используйте распространенные, повседневные слова и избегайте жаргона, когда это возможно. Термины, хорошо известные разработчикам, но не предполагают, что читатель знает подробности о том, как работает GitHub.
- Используйте активный голос.
- Будьте краткими.
- Напишите предложения, которые являются простыми и краткими.
- Избегайте сложных предложений, содержащих несколько понятий.
- Синтаксический анализ ненужных сведений.
Дополнительные сведения см. в разделе "Голос и тон" в [AUTOTITLE и Руководство по стилю](/contributing/writing-for-github-docs/writing-content-to-be-translated).
Формат для проверки
Большинство читателей не потребляют статьи в целом. Вместо этого они сканируют_ _страницу, чтобы найти определенную информацию, или пропустить страницу, чтобы получить общее представление о понятиях.
При сканировании или сканировании содержимого средства чтения пропускают большие фрагменты текста. Они ищут элементы, связанные с их задачей или выделяющиеся на странице, такие как заголовки, оповещения, списки, таблицы, блоки кода, визуальные элементы и первые несколько слов в каждом разделе.
После четко определенной цели и структуры статьи можно применить следующие методы форматирования для оптимизации содержимого для сканирования и очистки. Эти методы также могут помочь сделать контент более понятным для всех читателей.
- Используйте выделение текста, например полужирный шрифт и гиперссылки , чтобы привлечь внимание к наиболее важным пунктам. Используйте выделение текста с разреженным образом. Не выделите более 10 % общего текста в статье.
- Используйте элементы форматирования для разделения содержимого и создания пространства на странице. Например:
- Маркированные списки (с необязательными подзаголовоками запуска)
- Нумерованные списки
- Оповещения
- Таблицы
- Визуальные элементы
- Блоки кода и заметки кода
Дополнительные материалы
- "Руководство по стилю"
- "О con режим палатки l"
- "Содержимое статьи GitHub Docs"
- "Рекомендации по удобочитаемости", дизайн содержимого Лондона
- "Переписать цифровое содержимое для Краткости", Nielsen Норман Group