Skip to main content

Тип контента учебника

Учебники полезны, если у кого-то есть базовое понимание продукта и заинтересованы в расширении их понимания для решения конкретной проблемы

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

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

Мы совместно ссылаемся на учебники и краткие руководства как "руководства" по всему сайту. На /guides целевых страницах мы включаем руководства, краткие руководства и некоторые процедурные статьи в список руководств для набора документов.

Создание учебника

Шаблон руководства см. в разделе "Шаблоны".

Содержимое учебников:

  • Введение
    • Уточняет аудиторию.
    • Четко указывает необходимые условия и предварительные знания.
    • Указывает, что кто-то будет выполнять или строить.
    • Включает пример успешного проекта.
    • Не включает ожидаемое количество времени, которое может занять кто-то для выполнения задачи. Это зависит от уровня опыта пользователя, выполняющего учебник.
  • Процедурные разделы
    • На основе аудитории руководства шаги могут быть менее явными и формальными, чем те, которые используются в процедурном содержимом. Вам не нужно использовать существующие многократно используемые средства для формирования этих шагов, если аудитория не требует этого уровня детализации.
      • Используйте команду "Из профиля щелкните "Параметры" и выберите "Параметры разработчика".
      • Избегайте. В правом верхнем углу любой страницы щелкните фото профиля и нажмите кнопку "Параметры". На левой боковой панели щелкните Developer settings (Параметры разработчика).
    • Ссылки на другие статьи или ресурсы, а не репликацию их, чтобы избежать прерывания потока информации в руководстве.
    • Предоставьте визуальные подсказки. Используйте блоки кода и снимки экрана, чтобы убедить людей, что они выполняют правильные действия.
    • Укажите реальные примеры.
      • Например, не сообщайте пользователю "Ввести сообщение о фиксации" вместо этого присвойте им соответствующий пример фиксации сообщения, соответствующего предыдущим шагам.
  • Устранение неполадок
    • Подтвердите, что может пойти не так в задаче, и перечислите несколько распространенных проблем, которые читатели могут столкнуться с решениями.
  • Заключение
    • Просмотрите, что было сделано или построено. Вернитесь к проекту, указанному в вводном представлении, в качестве примера успешного проекта.
  • Следующие шаги
    • Включите 2-3 действия, которые можно предпринять после выполнения руководства. Связывание с другими связанными сведениями, например:
      • Проекты на GitHub, иллюстрирующие представленные понятия
      • Соответствующая информация о docs.github.com
      • Релевантные данные GitHub Skills
      • Соответствующие опубликованные переговоры, записи блога или публикации серии форумов сообщества Hubbers

Руководство по заголовку учебников

  • Следуйте инструкциям по заголовкам процедурных статей.
  • Не используйте "учебник" или "руководство" в заголовке.

Примеры учебников

Руководства.

Руководства по языку и платформе: