Лучшие методы обмена фрагментами кода и скринкастами, которые помогут продвинуть ваши проекты с открытым исходным кодом к успеху.
Введение
Создание собственных проектов с открытым исходным кодом может быть чрезвычайно полезным, но бывает трудно пробиться сквозь шум и заставить других разработчиков доверять и использовать ваше программное обеспечение. Вы можете добиться значительных успехов, следуя общепринятым лучшим практикам таким как включение надежной документации, добавление модульных тестов, интеграция с CI/CD, ориентированным на проекты с открытым кодом (например travis-ci или circle-ci), и соблюдение последовательных стилевых соглашений.
Один из наиболее эффективных и простых способов выделения проектов с открытым исходным кодом из толпы - это добавление качественных скриншотов или анимированных демонстраций. Когда я вижу такое внимание к деталям, это не только доказывает, что автор заботится о проекте, но и является самым быстрым способом передать, что же на самом деле делает проект.
Фотография стоит тысячи слов. - Клишированная поговорка, которая полностью соответствует действительности
Включение качественных скриншотов и демонстраций становится все более важной частью того, что я бы назвал Разработчик UX, т.е. того, как потенциальный разработчик проходит путь от рассмотрения возможности добавления вашего проекта в качестве зависимости до его успешной интеграции и дальнейшего сопровождения.
В связи с этим мы рассмотрим три распространенных варианта использования мультимедиа для улучшения пользовательского интерфейса разработчиков в ваших проектах с открытым исходным кодом:
- Статические фрагменты кода (изображения)
- Анимированные примеры кода (GIF-файлы или анимированные SVG)
- Скринкасты проекта (видео
Статические фрагменты кода
Обмен небольшими фрагментами статического кода, безусловно, является наиболее распространенным и важным вариантом использования в этом списке. В readme каждого проекта с открытым исходным кодом должно быть несколько легко разбираемых примеров использования фрагментов, поэтому давайте начнем с них.
GitHub-Flavored Markdown Snippets
AВ самом простом варианте GitHub позволяет использовать подсветить синтаксис в фрагментах кода в формате markdown. Надеюсь, этот стиль встраивания вам знаком, а если нет, то я бы определенно рекомендовал начать с этого.
const pMap = require('p-map') const got = require('got') const sites = [ getWebsiteFromUsername('sindresorhus'), //=> Promise 'ava.li', 'todomvc.com', 'github.com' ] const mapper = el => got.head(el).then(res => res.requestUrl) pMap(sites, mapper, { concurrency: 2 }) .then(result => { console.log(result) //=> ['http://sindresorhus.com/', 'http://ava.li/', 'http://todomvc.com/', 'http://github.com/'] })
GitHub Gists
Приведенный фрагмент кода также является примером чрезвычайно популярного способа обмена статическими фрагментами кода через GitHub Gists, который обладает следующими преимуществами:
- Линкабельность
- Поддержка версионности
- Поддержка обсуждения с помощью комментариев
- Выделение синтаксиса
Carbon
Markdown сниппеты и GitHub gists полезны, но если вы действительно хотите сделать свой код более ярким, то обратите внимание на Carbon.
Carbon - это очень популярный проект с открытым исходным кодом, позволяющий легко создавать эстетически привлекательные скриншоты кода, а также множество вариантов настройки и плагинов сообщества. Это отличный выбор для выделения изображения героя в readme, повышения вовлеченности в социальных сетях или для написания постов в блоге, связанных с инженерной тематикой, как, например, этот 😛.
Анимированные примеры кода.
Включение высококачественной встроенной демонстрации, быстро демонстрирующей основное назначение вашего проекта, является самым важным советом, который я могу дать.
Однако существует множество различных способов создания таких демонстраций, поэтому я хотел бы обсудить здесь наиболее эффективный, на мой взгляд, подход.
Asciinema это бесплатный инструмент, позволяющий записывать и делиться своими терминальными сессиями.
Asciinema предоставляет легкий, чисто текстовый подход к записи терминальных сессий, позволяющий делать записи без потерь, которые затем могут быть переданы напрямую или преобразованы в анимированный SVG, GIF или видео. Меня удивило, как много популярных проектов с открытым исходным кодом на GitHub используют Asciinema - очень рекомендую ознакомиться с ним.
Анимированнаый SVG or GIFs?
Все мы знаем, что GIF - ужасно неэффективный формат с потерями, но давайте немного углубимся в этот конкретный случай использования.
Сравните приведенный выше встроенный скринкаст gif с анимированным SVG того же скринкаста из readme.Трудно вставить встроенное сравнение рядом, но анимированный SVG значительно четче и меньше, его размер составляет 73 Кб против 4,4 Мб у менее качественного GIF.
Почему это вообще обсуждается? Ну, вы же не можете включить пользовательский HTML в запись блога Medium, не так ли? И, если уж на то пошло, есть много мест, где использование пользовательских анимированных SVG не пройдет, и в обозримом будущем GIF будут жить как запасной вариант для таких случаев. Но авторы проектов с открытым исходным кодом, пожалуйста, рассмотрите возможность использования анимированных SVG вместо GIF для своих проектов на GitHub!
На GitHub есть несколько очень популярных проектов с открытым исходным кодом, которые начали использовать более эффективные анимированные SVG для своих демо-версий, например create-react-app, но в целом GIF-файлы встречаются гораздо чаще.
Вот несколько примеров использования замечательной программы svg-term-cli для генерации нашего анимированного SVG без потерь.
# generate animated SVG svg-term --cast 'fxdtpprue51QZkeViQurqPg8V' --out demo.svg --window --width=80 --height=24 --term=iterm2 --profile=Snazzy # generate single frame SVG at 20 seconds into the screencast svg-term --cast 'fxdtpprue51QZkeViQurqPg8V' --out screenshot.svg --window --width=80 --height=24 --term=iterm2 --profile=Snazzy --at 20000
It’s important to note that when discussing animated SVGs, we’re really talking about embedding an HTML snippet into GitHub-flavored markdown that links to an SVG file encoded with each frame as an SVG group and the animation defined via CSS keyframes (example SVG source).
<p align="center"> <img width="600" src="https://cdn.rawgit.com/transitive-bullshit/create-react-library/master/media/demo.svg"> </p>
IВставьте этот HTML-сниппет в любой файл разметки на GitHub, чтобы вставить в него связанный анимированный SVG с оптимальной резкостью и малым размером по сравнению с аналогичным GIF.
Для справки, здесь приведен скринкаст из create-react-library который мы использовали в качестве примера в нескольких различных форматах:
- Оригинальный asciicast
- Высокое качество animated SVG созданный с помощью svg-term-cli
- Низкое качество GIF созданное с помощью asciicast2gif
Захват и оптимизация GIF-файлов
Asciinema отлично подходит для записи в терминале, но что делать, если вы хотите записать компонент пользовательского интерфейса или веб-сайт? Мой первый и главный ответ здесь - всегда включать в свой проект, по возможности, пригодную для использования демонстрацию, особенно если это фронтенд-веб-проект. Это очень легко сделать с помощью GitHub Page’s бесплатного хостинга!
IfЕсли вы хотите включить в проект GIF, я рекомендую использоватьr GIPHY Capture или Kap для записи экрана и вывода GIF. Если же у вас есть видео, записанное с другого источника, я рекомендую использовать Gifski для преобразования видео в оптимизированный GIF для удобства встраивания.
<!-- html snippet customizing embedded gif --> <img src="https://cdn.rawgit.com/terkelg/prompts/master/media/number.gif" alt="example prompt" width="499" height="103" /> <!-- raw markdown can also be used to ambed a gif --> 
Project Screencasts
Если ваш проект становится все более масштабным или вы представляете его широкой аудитории, включение видеороликов с описанием проекта может оказать реальную помощь в освоении и поддержке пользователей.
Screenflow
Я предпочитаю использовать программу для записи экрана ScreenFlow, оторая стоит недешево - 129 долларов США, но за эту цену предоставляет множество мощных и качественных инструментов, включая точную запись прямоугольного экрана, микширование видео и аудиодорожек, озвучивание, эффекты перехода и многое другое. Этот тип скринкаста несколько сложнее, чем скриншоты и записи терминальных сессий, которые мы рассматривали ранее.
Вывод
UX разработчика важен для продвижения и маркетинга вашей работы, что, в свою очередь, может привести к вполне реальным последствиям, так как быть замеченным за свой вклад в разработку открытого кода - это, безусловно, один из лучших способов добиться известности и получить большие возможности для работы в качестве инженера-программиста.
Надеюсь, что некоторые из описанных мною приемов помогут вам в продвижении ваших проектов с открытым исходным кодом. Если вы нашли эту статью полезной и в итоге создали привлекательный скриншот или анимированную демонстрацию, добавьте комментарий со ссылкой на ваш проект и дайте мне знать!
И, как всегда, не забывайте распространять ❤️... конечно же, в виде красивых демонстраций кодирования!