Как стать автором
Обновить
127.46
Яндекс Практикум
Помогаем людям расти

Правки на мёрдже: зачем редактору GitLab

Время на прочтение 9 мин
Количество просмотров 5.6K

Всем привет! Меня зовут Наталья Которева, я редактор в Яндекс.Практикуме. В этой статье я расскажу, как мы создали обучающий курс в GitLab. Да-да, вместо текстовых документов.

Вообще сложно представить, как можно подружить git и редактуру, а главное, зачем. Есть же много проверенных инструментов, с помощью которых можно без проблем писать текст и потом его всячески править. Но, как выяснилось, привычные гуглдоки и ноушен не особо подходили под наши запросы, поэтому пришлось искать альтернативу. 

Сегодня я расскажу, с какими проблемами мы столкнулись, когда писали курс «Мидл Python-разработчик», зачем перенесли работу с контентом в GitLab и почему это оказалось хорошей идеей. Будет полезно почитать всем, кто так или иначе работает с контентом: редакторам, контент-менеджерам, специалистам по развитию бренда и тем разработчикам, которые создают контент сами. 

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

С чего всё началось и чем нас не устроил ноушен

Начну с пары слов о том, как создаются курсы в Практикуме, чтобы упростить погружение в контекст истории. Каждый курс — это отдельный проект с продактом, техлидом и разработчиками. Только последние выступают не в привычной роли — они становятся авторами. Для нас важно, чтобы обучающий контент писали те, у кого есть богатый опыт в разработке и понимание, как что работает в боевых условиях.

И здесь нас поджидает несколько проблем. Разработчики — не копирайтеры или журналисты. Они не обязаны писать текст — им нужно писать код. Помимо этого у части разработчиков был не самый позитивный опыт в плане текстов. Например, кто-то писал статью, а потом получал фидбек, что она слишком тяжело читается или опубликована со стыдными грамматическими ошибками. Или текст вроде бы написался легко, но потом были бесконечные итерации с правками и доработками. Да и в целом для разработчиков процесс редактуры не всегда понятен, поэтому у них есть доля страха, что придёт редактор и всё не так поймёт: внесёт кучу правок, уберёт все важное или неправильно перепишет.

В общем, от проблем с техническим контентом страдают многие — это неизбежно. С ними столкнулась и наша команда, которая писала курс «Мидл Python-разработчик». 

Летом 2020 года курс только-только обретал свою форму, а вся команда училась взаимодействовать друг с другом. У нас было два автора, 15 стартовых тем для бесплатного модуля и меньше 50 дней до релиза. Для ребят-разработчиков это был первый опыт написания обучающего контента, а для меня вообще новая тема: максимум, что я знала, — чем отличается монолит от микросервисов, что такое Докер и как работают базы данных. Так получилось, что мы перекрёстно обучали друг друга: я начинала въезжать в бэкенд, а они — в структуру текста.

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

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

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

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

Ещё один минус я осознала, когда выкладывала готовые уроки в админке курса. В ноушене у текста вполне стандартное форматирование, а в админке поджидал markdown. Так что мы теряли время и на вёрстке урока.

Здесь авторам пришла на ум гениальная мысль. Курс — это групповой проект. Каждый пишет свой текст, сохраняя его версия за версией. Все изменения отслеживаются и хранятся в истории, поэтому можно безболезненно вернуться к нужному варианту. А когда всё готово, итог работы можно добавить в основной курс.

Что бы это могло быть?

Конечно же, git.

Как мы приспособили GitLab под тексты

Всю дальнейшую работу мы стали вести в GitLab. Для тех, кто видит git впервые, он кажется страшным, особенно для тех, кто ни разу не программист. Сильно тормозит тот факт, что эти все штуки — чисто для разработчиков, редактор или копирайтер тут никогда не разберётся и только всё поломает. К тому же, многие даже не допускают мысли, что GitLab можно использовать для чего-то ещё, кроме кода. Ну, и редактировать в нём явно сложнее, чем в привычных гуглдоках. 

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

Ещё один дисклеймер: кроме GitLab есть и другие сервисы, которые работают с git. Например, его популярный собрат GitHub. Самая большая разница заключается в том, что проекты, созданные в GitLab, могут находиться в частном репозитории бесплатно, а GitHub потребует подписку. Ещё есть небольшие отличия в механике их работы, но в случае текстов они не так важны.

Краткий экскурс в работу GitLab

Весь проект хранится в одной папке — репозитории.

Все готовые и утверждённые части проекта находятся на главной странице — это отображение состояния мастер-ветки.

Чтобы поработать над написанием текста, автор создаёт копию мастер-ветки. Так получается рабочая ветка (branch) с уникальным названием. Автор спокойно пишет в ней урок и никому не мешает.

Когда автор закончил работу, создаётся запрос на добавление изменений в мастер-ветку — merge request (MR).

Если другой автор или редактор внесёт какие-либо изменения в текст автора, то они попадут в новую версию файла через коммит — это аналог кнопки «Сохранить».

Когда все изменения утверждены, ветку автора можно объединить с мастер-веткой — merge (или просто «смёрджить»). Если всё хорошо, текст автора попадает в главное хранилище проекта. Но если вдруг над этим же текстом параллельно работал другой автор, то возникнет конфликт: система не сможет понять, какой файл нужно залить в мастер. Здесь придётся отсмотреть изменения и решить, что же оставить.

Работу над контентом мы выстроили так:

Технический лид курса согласовывал темы с тимлидом и методистом. Каждый автор получал свою тему и писал по ней серию уроков в отдельной ветке. 

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

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

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

После этого уроки в GitLab мёрджились в мастер-ветку, чтобы ничего не потерялось. Если приходили какие-то правки, то они вносились одновременно на платформе и в GitLab.

Чем же так хорош GitLab для создания контента

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

В GitLab всё уже организовано за вас: у авторов есть отдельные рабочие пространства для каждого урока, и они не мешают друг другу. Всё собрано по папкам, поэтому не нужно копировать ссылки на уроки в отдельную таблицу. А ещё там можно прекрасно организовать привычную канбан-доску с задачами и назначать ответственных.

Понятные процессы работы с контентом. GitLab естественным путём помог нам организовать процесс создания уроков. Для меня это стало чем-то удивительным: раньше я организовывала рабочие процессы внутри нескольких редакций, и мне приходилось придумывать разные сочетания инструментов. Здесь же сама система продиктовала все процессы. 

Комфорт авторов. Для авторов работа в GitLab была более понятной, чем в ноушене. Всё было знакомо: не нужно изобретать велосипед в плане внесения новых кусков текста или постоянным копированием версий уроков. В целом им было проще относиться к тексту как к коду. Но был и минус: пришлось отучать от привычки писать каждое предложение с новой строки. 

А ещё авторы могли протестировать работу тех частей уроков, где был написан код. 

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

Все изменения в тексте подсвечиваются: красным — удалённые кусочки, а зелёным — добавленные. Авторы всегда видели, где я переписала текст, и могли проверить его на фактические ошибки, а я видела, где автор что-либо дописал после моей проверки. Впоследствии, когда мы перешли к рефакторингу курса, подсветка изменений сильно упростила поиск нужного урока в админке и того, что нужно в нём заменить. 

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

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

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

В GitLab все уроки сразу писались в markdown, поэтому мне было достаточно скопировать содержимое файла, вставить в админку и проверить, что вёрстка нигде не поплыла.

А есть ли минусы?

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

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

В моём случае наша команда была сильно ограничена во времени, поэтому я не могла спокойно разобраться, что к чему. Были и неприятные моменты набивания шишек: например, однажды пришлось восстанавливать урок по кусочкам, потому что я редактировала его параллельно с автором. Понимание пришло в процессе работы, а ещё помогло чтение статей на Хабре и книжка Pro Git

Непривычная система комментариев. Редакторы привыкли к простому созданию комментария в тексте: выделил нужный кусочек, нажал на иконку, и готово. В GitLab такое не прокатит. Здесь нет возможности оставить комментарий сразу в тексте — только после того как сохранишь (закоммитишь) изменения. Приспособилась я достаточно просто: записывала номер строки и оставляла комментарий после коммита.

Но в GitLab есть ещё один вид комментариев — в merge request. Здесь можно оставить комментарии не к конкретной строке в файле, а к MR в целом.

Риск пропажи контента. Бывали ситуации, когда что-то шло не так и при слиянии веток, и у нас пропадали целые разделы. К счастью, утраченное было легко восстановить, скопировав урок с платформы. Всё решается осторожным закрытием merge request — не стоит копить их в большом количестве, чтобы потом не возникали конфликты между ветками. 

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

Что нужно, чтобы запустить редакцию в GitLab или GitHub

Изучить терминологию. Если вы никогда не работали с git, попытайтесь как-то уложить в сознание новые сущности, с которыми вам придётся работать. 

Словарик начинающего гитёнка

git — система контроля версий, которая помогает отслеживать историю изменений в файлах.

GitLab и GitHub — инструменты для хранения и управления репозиториями git.

Репозиторий — хранилище всех файлов и изменений проекта.

Мастер-ветка (master) — основная ветка проекта, которая хранит утверждённые изменения.

Рабочие ветки (branches) — отдельные рабочие пространства, которые копируют мастер-ветку.

Merge request (MR) — запрос на внесение изменений.

Коммит (сommit) — запись в истории изменений файлов, аналог кнопки «Сохранить».

Мёрдж (merge) — слияние рабочей ветки с утверждёнными изменениями с мастер-веткой.

Конфликт — противоречие между версиями файла.

Понять, как работает сервис. Ещё стоит понять, где и что находится в GitLab или GitHub — в целом их интерфейсы похожи. Можно создать тестовый репозиторий и несколько папок с файлами и ставить эксперименты. А чтобы они были осознанными, можно руководствоваться документацией GitLab или GitHub.

Изучить markdown-разметку. Нужно смириться, что у GitLab и GitHub нет визуального редактора — только режим просмотра. Все болды и курсивы, заголовки и списки размечаются символами. Сначала это сильно мешает восприятию текста, и приходится часто заглядывать во вкладку Preview, но со временем привыкаешь и запросто считываешь разметку. Но есть хорошая новость: markdown-разметка очень простая, в отличие от того же HTML.

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

  • проекты со множеством текстов,

  • образовательные курсы,

  • проекты со сложной иерархией,

  • создание редакции и отладка внутренних процессов,

  • проектирование сайта или других связанных систем,

  • работа с книгами,

  • написание серии технических статей с разработчиками.

Нет смысла переносить работу с контентом в GitLab, если вы работаете с одиночными текстами или с парой авторов. 

Только зарегистрированные пользователи могут участвовать в опросе. Войдите, пожалуйста.
Насколько бы вам было удобно работать с контентом в GitLab или GitHub?
70.37% Это интересно, я попробую 19
22.22% Сомневаюсь, что это хорошая идея, но интересно 6
7.41% Зачем, ведь есть гуглдоки и ворд 2
Проголосовали 27 пользователей. Воздержались 13 пользователей.
Теги:
Хабы:
+12
Комментарии 13
Комментарии Комментарии 13

Публикации

Информация

Сайт
practicum.yandex.ru
Дата регистрации
Дата основания
Численность
101–200 человек
Местоположение
Россия
Представитель
Ира Ко