Перейти к основному содержимому

Как внести вклад в проект

Мы рады приветствовать новых контрибьюторов в нашем проекте! Этот документ поможет вам разобраться, как внести свой вклад в развитие проекта Learn Agents - интерактивной книги об AI Агентах.

Что такое контрибьютинг?​

Контрибьютинг - это процесс внесения вклада в открытый проект. Вклад может быть разным:

  • Создание новых модулей или блоков
  • Обновление устаревшей информации
  • Перевод на другие языки
  • Исправление минорных ошибок в контенте
  • Улучшение UI/UX
подсказка

Для внесения быстрых изменений, вы можете нажать на кнопку "Edit this page" внизу каждой страницы.

Зачем это мне?​

  • Центр обмена экспертизой: вы можете поделиться своим опытом и знаниями с другими и получить обратную связь
  • Волонтерство: для развития личного бренда, прокачки резюме
  • Обучение использованию вашего продукта

Какие страницы нужны как можно скорее?​

У меня есть инсайд, но нет времени написать материал​

Как начать​

гордитесь тем что вы делаете

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

Философия​

  1. Прочитайте страницу /intro "Об учебнике": ценности, принципы
  2. Перед написанием модуля, рекомендуется согласовать тему с советом преподавателей. Как? тг

Как писать модуль с нуля​

Шаблон модуля

Каждый модуль - страница на данном сайте - состоит из следующих частей:

Введение​

Начните с краткого введения, которое объясняет, что будет изучаться на этой странице. Добавьте мотивацию, чтобы заинтересовать читателя. Хорошая мотивация - решение жизненной проблемы, промышленный кейс, история неудачи.

Цели обучения: Определите, что читатель должен уметь делать после изучения материала. Это поможет сфокусировать внимание на ключевых аспектах.

Вопросы​

Перечислите основные вопросы, которые будут обсуждаться. Это поможет читателю понять, на что обратить внимание.

Шаги обучения​

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

В основные шаги должно попасть как можно меньше материала - но достаточно, чтобы осваивать следущие модули и найти Applied AI работу (как ориентир)

Дополнительные шаги: Включите дополнительные шаги для более глубокого изучения темы, если это необходимо.

Подытог модуля​

его полезно прочитать, чтобы мозг еще раз пробежался по материалу

Exercises​

Сложные вопросы. Во время размышления над ними вам будет тяжело, но это нормально. Именно в этот момент мозг активно формирует новые нейронные связи.

Рассказ о своем продукте или теме, косвенно относящейся к агентам​

Selling is helping - но ваш продукт может присутствовать в уроке лишь косвенно. Также вы будете должны рассказать про конкурентов.

  • Если напрямую бьётся с агентами и critical знание для работы, то идёт в родмапу

  • Если бьётся с агентами но для работы знание не обязательное, то идёт в родмапу с пометкой бонусного/профессионального материала (зелёная/фиолетовая галочка на карте)

  • Если с агентами не бьётся, помещается в extra блок, с ссылками на страницу из основной программы Или на страницах основной программы, но в экстра шагах

Как вносить материал в репозиторий​

Как вносить материал в учебник

  1. Форкните репозиторий
    Создайте форк нашего основного репозитория:

  2. Клонируйте свой форк на локальную машину

  3. Введите команды:

    # Установите зависимости
    npm install

    # Запустите локальную версию
    npx docusaurus start --locale ru

  4. Внесите изменения в файлы

  5. Создайте Pull Request

Может помочь видео (и чатгпт):

Создание контента​

Советы по созданию контента

Документация Docusaurus​

Markdown Features​

Структура проекта​

Контент размещается в следующих директориях:

  • Английская версия: /docs/
  • Русская версия: /i18n/ru/docusaurus-plugin-content-docs/current/

Форматирование​

  • Используйте Markdown для базового форматирования
  • Для более сложных компонентов используйте MDX
  • Изображения храните в /static/img/

Пример добавления нового материала​

  1. Создайте новый файл .mdx в соответствующей директории
  2. Добавьте метаданные в начало файла: 
    ---
    sidebar_label: Название для боковой панели
    ---

    # Заголовок страницы
  3. Напишите и отформатируйте ваш контент

Добавление страницы в навигацию​

Чтобы ваша новая страница отображалась в боковой панели навигации, необходимо добавить её в файл sidebars.ts в корне проекта:

  1. Откройте файл sidebars.ts
  2. Найдите соответствующую категорию для вашей страницы
  3. Добавьте путь к вашему файлу в соответствующий раздел:
// Пример добавления новой страницы в категорию Handbook
{
  type: 'category',
  label: 'Handbook',
  items: [
    'handbook/introduction',
    'handbook/contributing', // существующие страницы
    'handbook/ваша-новая-страница', // ваша новая страница
  ],
},

Обратите внимание, что путь указывается без расширения .mdx и относительно директории docs/ или i18n/ru/docusaurus-plugin-content-docs/current/.

Процесс ревью​

После создания Pull Request ваши изменения будут рассмотрены командой проекта. Мы можем попросить внести некоторые корректировки. После успешного ревью ваши изменения будут приняты в проект.

Рекомендуется взаимодействовать с командой: тг

Благодарность​

Большое спасибо за ваш вклад в проект! Вместе мы делаем знания об AI Агентах доступнее для всех.

Как указать себя автором материала​

Как указать себя автором материала

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

1. Добавьте информацию о себе в файл авторов​

Данные об авторах хранятся в файле blog/authors.json. Добавьте свою информацию в формате JSON:

{
  "ваш_ключ": {
    "name": "Ваше Имя",
    "title": "Ваша должность или роль",
    "url": "https://github.com/ваш-аккаунт",
    "image_url": "https://github.com/ваш-аккаунт.png",
    "socials": {
      "github": "ваш-аккаунт",
      "linkedin": "ваш-профиль-linkedin",
      "email": "ваша-почта@example.com",
      "x": "ваш-аккаунт-twitter"
    },
    "description": "Краткое описание о вас (опционально)"
  }
}

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

2. Укажите себя автором в frontmatter вашей страницы​

В начале вашего .mdx файла добавьте поле authors в секцию frontmatter:

---
sidebar_label: Название для боковой панели
authors: ваш_ключ
---

# Заголовок страницы

Вы также можете указать несколько авторов через массив:

---
sidebar_label: Название для боковой панели
authors: 
  - ваш_ключ
  - другой_автор
---

Или указать информацию об авторе напрямую:

---
sidebar_label: Название для боковой панели
authors:
  - name: Ваше Имя
    title: Ваша должность или роль
    url: https://github.com/ваш-аккаунт
    image_url: https://github.com/ваш-аккаунт.png
    socials:
      github: ваш-аккаунт
---

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

примечание

Убедитесь, что ключ автора в authors точно совпадает с ключом в файле blog/authors.json, иначе информация об авторе не будет отображаться.