Задать вопрос Поделиться знаниями Редактировать страницу

Участие в создании гайда

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

Пару раз в месяц редакция проводит рабочие встречи в разных форматах. Мы обмениваемся знаниями и фиксируем идеи в этом гайде.
Часть встреч проводится открыто и вы можете присоединиться к нам. Лучший способ узнать о таких встречах — подписаться на Telegram канал @pragmatic_km и следить за объявлениями.
Вы также можете задать вопросы сообществу специалистов в управлении знаниями в чате "Я шарю".

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

Для того, чтобы пойти этим путём, необходимо:

Зарегистрироваться на платформе Gitlab (если вы ещё этого не сделали)
Подтвердить учётную запись в письме от Gitlab
Зайти в раздел Issues в репозитории нашего гайда и оформить свои мысли в произвольном виде заполнив поля Title и Description и нажав "Submit Issue"
Следить за письмами в вашей почте: когда редакция будет что-то комментировать в GitLab по вашей заявке — вам будут приходить письма.

Более сложный путь (для тех, кто умеет работать с Git и Gitlab) — самостоятельно внести изменения в статьи репозитория и оформить Merge Request. На данном этапе развития гайда у нас нет специальных правил на именование веток или оформление статей, главное — это качественный контент.

Самый простой способ исправить опечатки — это отредактировать страницу непосредственно через платформу GitLab. Это требует от вас базовых навыков работы с GitLab и наличия учётной записи на этой платформе.

На каждой странице есть кнопка "Редактировать страницу", которая ведёт на соответствующую форму редактирования на платформе GitLab.

Если вы понимаете, что в статье по какой-то теме не освещены важные аспекты — жмите на кнопку "Задать вопрос". Мы отправим ваш вопрос в сообщество специалистов где, возможно, сможем совместными усилиями найти ответ для вас.

Другой способ (для тех, кто умеет работать с Git и Gitlab) — самостоятельно вписать свои вопросы в статьи репозитория и оформить Merge Request. Мы считаем, что статья с правильными, глубокими вопросами по теме — это чек-лист для погружающегося в тему, и это имеет высокую ценность.

Если вы правите статьи у себя на компьютере, удобно сразу видеть результат — сайт можно собрать и открыть локально. Это не обязательно: правки через веб-интерфейс GitLab тоже работают, а собранный вариант ветки покажет CI после оформления Merge Request.

Из корня репозитория выполните:

./bin/serve

Скрипт сам поставит зависимости при первом запуске и откроет сайт на http://localhost:4000. Остановить — Ctrl+C.

Пока скрипт работает, правки в .html, .md и _data/*.yml подхватываются автоматически, страница в браузере перезагружается сама. Единственное исключение — _config.yml: после его правки скрипт нужно перезапустить.

Что полезно знать:

Нужен Ruby версии 3 или новее. Системный Ruby в macOS (2.6) не подойдёт — на нём не устанавливаются зависимости. Скрипт сам найдёт подходящий Ruby в ~/.rubies, а если его нет — подскажет команду установки. В CI сайт собирается на Ruby 3.1.
Если порт 4000 уже занят, запустите на другом: PORT=4002 ./bin/serve. Скрипт заранее проверяет порты и пишет, какой процесс их держит.
Зависимости ставятся в папку .vendor внутри проекта, а не в систему. Она, как и папка со собранным сайтом _site, уже исключена из репозитория — коммитить их не нужно.