Как в GitHub пишут посты для блога

GitHub для GitHub

Вы, возможно, слышали о том, что возможности GitHub используются, чтобы создавать GitHub.

Не секрет, что компания… слегка необычна. Было бы непросто найти другую организацию с таким количеством юристов, знающих, как работать в Git. Но GitHub — это не один программный код: у проекта есть своя стратегия и кадровая политика, своя система коммуникации между сотрудниками и множество других правил, которые также должны быть оформлены письменно. И все это может быть сделано при помощи GitHub.

Посты для блога

Позволить команде разработчиков написать свой собственный анонс — это хорошее подтверждение значимости проделанной ими работы. Подобное практиковали в компании Apple: в ранних приложениях для Macintosh в окнах с описанием программы показывались имена авторов. Поддержка друг друга при успешном завершении чего-либо — это по-настоящему важная составляющая правильной корпоративной культуры. Успех вдохновляет.

Информация, которая размещается в блоге, должна была понятной и осмысленной. Очень эффективный способ это выполнить — узнать мнение людей со стороны. Поэтому, как в случае с кодом, записи для блога GitHub корректируются с помощью практики pull request («запрос на включение произведенных изменений»). Пользователь создает новую тему в репозитории записей в блоге, пишет новый драфт, а затем оформляет pull request, чтобы начать обсуждение (и все это можно сделать, не покидая GitHub.com).

В качестве примера – список критериев, по которым в настоящее время обычно осуществляется предварительная проверка текста:

– Обязательное использование атрибута alt при работе с изображениями.

– Использование изображений размером менее мегабайта. Это помогает избежать включения в пост скриншотов, которые могут «весить» очень много и будут замедлять работу со страницей с мобильных устройств. 

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

– Загрузка изображений через CDN. Все картинки должны загружаться через сеть CDN, чтобы увеличить производительность, безопасность и эффективность работы.

– Никаких «смайлов». GitHub использует их постоянно, но это не совсем уместно при оформлении официальной информации, обращенной к пользователям.

– Никаких «Сегодня…». В гигантском количестве старых постов GitHub текст начинается по типу: «Сегодня мы с радостью представляем вам…». Это попросту несерьезно. В последующих записях команда решила избегать таких стандартных оборотов, чтобы разнообразить контент и заставить тексты звучать «по-человечески».

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

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

Тесты – это всего несколько элементарных строк кода на Ruby. Простая проверка не требует создания сложных решений. Если будет интересно, здесь можно найти пример кода, который используется GitHub в настоящее время.

Взаимодействие с коллегами

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

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

Безусловно, полезно обращаться к нужной команде при оформлении pull request. У GitHub есть множество редакторов по адресу @github/copy, которые будут рады помочь. Не менее полезно указывать название команды, которая работала над проектом, чтобы ваши коллеги тоже приняли участие в процессе.

Пример представления поста на GitHub

Редактирование

На этом этапе можно использовать инструменты, которые уже встроены в GitHub. Например, Prose Driffs обрабатывает черновик текста и показывает примерный вариант того, как будет выглядеть пост после публикации. GitHub применяет систему построчного комментирования для детальной корректировки текста, а также систему обычных комментариев к запросу на включение, чтобы получить более общие советы, например: «Как насчет того, чтобы завершить этот пост в таком-то ключе?».

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

Информационный обмен

То, как на GitHub пишутся посты, отражает практику проверки продукта «на себе». Подходит ли такой метод работы для вашей компании или нет — решать вам. Если нет, ознакомьтесь с другими инструментами для коллективной работы над текстами, такими как Google Docs. Кстати, любимый инструмент автора материала — это Draft от Нейтана Контни (Nathan Kontny).

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

Во-вторых, это делает информацию доступной для всех (по той же причине приветствуется обмен кодами на GitHub).

Делая общедоступными записи, над которыми работаете, вы получаете отзывы – они могут оказаться действительно оригинальными и полезными. А это – тот тип маркетинга, который ваши коллеги действительно оценят.

Фото: Shutterstock.

Оригинал статьи доступен здесь. Перевел для Кsusbae Дмитрий Кабанов, сооснователь контент-студии Rockin’Robin.