GitHub предоставил возможность миллионам разработчиков с легкостью публиковать свои проекты и тем самым привлекать пользователей и единомышленников. Часто перед разработчиками возникает проблема неэффективного использования ресурсов — они тратят сотни часов на создание проекта с целью продвинуть его на GitHub, а получают максимум две звезды.
Я оказался точно в такой ситуации, разрабатывая проект для некоммерческой организации Hack4Impact. Это студенческая группа, которая работает над техническими проектами для общественных организаций. Вместе мы разработали flask-base, которая использовалась как шаблонный код для всех наших продуктов. База данных включала в себя основные элементы flask веб-приложения: SQLAlchemy, Redis Queue и аутентификацию пользователя (наряду с несколькими другими функциями).
Вы можете ознакомиться с нашим репозиторием по ссылке.
Демонстрация бэкенда flask-base
Разработанная нами flask-base относится к категории «plug and play», что является главным его преимуществом. Установить работоспособную версию на компьютер не составляет большого труда (и ее можно запустить на хостинге, таком как Heroku). Кроме того, база крайне минималистична по сравнению с аналогами, ее очень удобно кастомизировать.
Разработка flask-base заняла два года и послужила шаблоном для 90% наших технических проектов. Проект помог претворить в жизнь продукты для таких организаций как Kiva, OSET, Juvenile Law Center, Givology.
Мы смогли помочь общественным организациям Америки достичь социального влияния, к которому они стремились. Несмотря на все наши попытки популяризировать наш код, flask-base осталась неизвестным в широких кругах, но стало полезным для людей, работающих с ней.
С чего мы начинали
Наши провальные попытки расширить аудиторию приводили к отчаянию, так как мы были уверены, что другие разработчики и небольшие компании могли бы использовать плод нашего труда для значимых проектов. Но мы никак не могли найти способ продвижения нашего продукта. В результате этого, мы подвергли сомнению честность источников с открытым исходным кодом, которые должны освещать отличные идеи для широкого круга потребителей.
То самое чувство
Впоследствии мы обнаружили ошибку нашего подхода. Мы внимательно изучили, каким образом работает открытый исходный код с точки зрения пользователя. Мы нашли ключевые области, которые нужно было пофиксить и усовершенствовали наш проект, чтобы он стал пригодным для
реального мира.
Мы попали в точку. Я запостил наш продукт в сабреддит /r/Python. В течение 48 часов наш репозиторий получил более 200 звезд по сравнению со стартовыми 9. И мы продолжали расти.
Внезапно мы начали получать комментарии и предложения от людей, которые были заинтересованы в нашем проекте, и это было превосходно.
прошлые дни += 544 stars, 74 forks, and 16 watches
Внезапно мы начали получать комментарии и предложения от людей, которые были заинтересованы в нашем проекте, и это было превосходно.
прошлые дни += 544 stars, 74 forks, and 16 watches
В этой статье мы хотим показать, каким образом наша flask-base заняла свою лидирующую позицию на GitHub. Если у вас есть значимый проект, вы можете легко использовать наш опыт и получить из него максимум.
Путь начинается с исследования
Мы начинали с анализа историй успеха. Популярные репозитории на GitHub имеют сходства:
- Обзор продукта содержит иллюстрации и гифки;
- Документация;
- Статический анализ кода;
- Уточняющие инструкции;
- Хорошо описанная инструкция к установке;
- Логотип.
Разбивка первых строк README
Хочу обратить ваше внимание на некоторые из лучших репозиториев GitHub:
- React-Router: более 19 тысяч звезд, 4,5 тысячи forks. ReactnRouter полезен в контексте управления отдельными страницами веб-приложений, а также является редким репозиторием, служащий туториалом по использованию структуры. Также он содержит исчерпывающий гид по установке, наряду с рекомендациями к ошибкам, с которыми могу столкнуться пользователи.
- Webpack: 23,5 тысячи звезд, 2,7 тысячи forks. Webpack можно назвать одним из лучших инструментов фронтенд-разработки, благодаря надежности и возможности разработки для разнообразных браузеров. README состоит из десятков знаков и примеров использования кейсов со ссылками на документацию. Webpack также подчеркивает роль общества в поддержке проекта (в частности, они имеют Sponsor и Backer секции)
Теперь приведем пример неудачного репозитория:
abhisuri97/leARn: я выбрал свой собственный репозиторий в качестве плохого примера – Hackathon проект, который выиграл PennApps XIII VR/AR и попал в Топ 10. Это был единственный проект, который я разрабатывал на Unity, имеющий огромное количество посторонних ненужных файлов. Наряду с подробным описанием функционала проекта, он не объясняет, как проект работает на конкретных системах и в чем его функции.
После анализа множества репозиториев и мониторинга основных трендов мы выделили ключевую концепцию: разработчик, изучающий ваш репозиторий нуждается в веской причине, почему ему стоит попробовать именно ваш проект, то есть в понимании, что продукт максимально прост и удобен в установке.
A.G.D. (Attention Grabbing Device – Методы привлечения внимания)
Красноречие и README:
В прошлом я принимал участие в конкурсах ораторского искусства, один из них назывался «Original Oratory» («Подлинное Красноречие»). Требовалось продекламировать жюри 10-минутную речь собственного написания. Каждое мое выступление начиналось с 2х минутного введения. Чаще всего это была история, предшествующая тезисам для речи, которые я собираюсь освещать.
По сути, README является A.G.D. вашего проекта!
README – первое, что увидит пользователь, обращаясь к вашему репозиторию. В связи с этим, стоит обратить пристальное внимание на его наполнение.
Но что является первостепенным и как завладеть вниманием пользователя? При ознакомлении с вашим проектом, пользователь должен знать:
- что это;
- насколько хорош код;
- какой саппорт доступен;
- что входит в проект;
- как он выглядит;
- как установить проект.
Давайте пройдемся по всем пунктам подробнее.
Что это
Огромный логотип сразу расскажет о вашем продукте
Самый простой вопрос о репозиториях, но многие люди неправильно его толкуют. Ваш проект один из миллионов существующих. У вас крайне мало времени, чтобы произвести впечатление.
Опишите ваш проект в твите (около 140 символов) – без лишних деталей: для них отведен раздел фич. Логотип также поможет, т.к. он выделяет название проекта среди черно-белого текста README (а также показывает ваши усилия, приложенные для его создания).
Насколько хорош код
Тот самый вопрос, на который 90% репозиториев не в состоянии ответить. В то время как определение «хорошего» кода субъективно, есть несколько основных характеристик:
- он хорошо протестирован;
- пройдена проверка стиля (ESlint);
- он может быть составлен в текущем виде;
- он прошел статический анализ (через такие сервисы как (Code Climate).
Дашборд Code Climate выдает вам cредний балл качества кода
Досконально изучать ваш код перед его использованием разработчикам не интересно. Равно как и «символы» на первой строке проекта. Особенность этих символов в легкости их применения, что делает проект действительно надежным в глазах посетителей, и им не нужно тратить время на изучение самого кода.
Какая техподдержка доступна
Саппорт состоит из двух видов: проблемы и обучение для пользователя. Саппорт по проблемам может быть реализован в FAQ. Но для новых проектов нет возможности узнать скрытые проблемы старого кода (и нет контента для FAQ). Единственное решение в данном случае – отвечать на вопросы, по ходу их возникновения и оперативно фиксить баги.
Документация flask-base, созданная с помощью mkdocs
Второй тип саппорта — это документация. Данная задача очень трудоемкая для разработчиков, но она крайне важна в контексте популярности проекта (и должна быть написана в любом случае).
Проще всего создать документы в mkdocs, и можно сгенерировать gh-страницы из mkdocs CLI, которую впоследствии можно перенести на хостинг GitHub.
Пользователи получат хорошие примеры того, как можно использовать проект и ознакомятся с объяснением тонкостей благодаря грамотно составленной документации. А также она будет детальным гидом к запуску проекта (если это веб-приложение).
Что входит в проект
X для Y
Список фич должен содержать ключевые особенности, входящие в демо-версию, то есть не должен быть чрезмерно обширным. Максимум 10 пунктов в формате «Х для фичи Y»
Как он выглядит
Демонстрационный пример функции редактирования страницы администратора flask-base
Картинка всегда лучше тысячи слов, поэтому лучше сделать .gif. Покажите как приложение работает, даже если это выход из командной строки. Данная информация предоставит возможность разработчику увидеть а) как будет выглядеть проект б) подходит ли для его нужд.
Не стоит недооценивать влияние хорошей графики на выбор разработчика в пользу вашего проекта.
Как установить проект
Копирование репозитория
Инициация Virtualenv
(Если вы работаете на маке) Убедитесь, что у вас установлен xcode
Добавьте переменные окружения
Cоздайте файл типа .env, содержащий переменные окружения, используя следующей синтаксис: ENVIROMENT_VARIABLE=value. Например, переменные окружения почты могут быть заданы таким образом:
Мы рекомендуем использовать Sendgrid в качестве почтового SMTP сервера, но любой другой также будет работать без проблем.
В процессе разработки вы работаете на одном компьютере, на котором уже установлены все нужные утилиты. Но пользователь должен иметь возможность установить ваш проект и начать с ним работу за 3-4 шага. Если это предполагает создание MakeFile, сделайте это. Обязательно стоит предупредить, если вы использовали «глобальные» инструменты, такие как babel-cli, babel-core.
Согласно основному правилу, если пришлось их использовать, то и другим придется это делать. Не забудьте сжать скрипты в единый файл (для Python это requirements.txt, а для node/javascript – package.json). Короче говоря, установка проекта должна занимать не более 5 минут.
Как попасть в тренд
Удержать пользователей поможет вам A.G.D. (README). Но как привлечь пользователей в ваш проект?
Есть три решения:
- Hacker News/Product Hunt: оба предоставляют отличную возможность осветить проект для заинтересованного круга разработчиков (и получить медиа обзор). Но существует сложность попадания в топы – размещение и продвижение проекта требует тщательного планирования и помощи от пользователей на старте.
- Reddit: самый эффективный метод получить стартовые звезды для вашего репозитория. Но нужно определить целевую аудиторию. Для нашего продукта этой аудиторией был /r/Python, где мы без труда вышли в топы.Важно обратиться к аудитории, заинтересованной в вашем проекте. Но нужно быть осторожным, если вы публикуете свой пост на таких крупных сабреддитах, как /r/Programming, где ваш пост может запросто затеряться среди прочих.
- Workshops: не секрет, что воркшопы – отличный способ получить десятки звезд. Сделайте воркшоп о том, как вы создавали проект, как он функционирует и как его использовать.
Veronica Wharton и я проводим воркшоп по Flask на PennApps XV
Мы использовали этот метод на PennApps XV: с помощью обучающего воркшопа создания веб-приложения с Flask. Аудитория состояла из примерно 40 человек, и мы показали свой продукт как пример Flask-приложения, которое они могли использовать во время хакатона. Через 5 минут после окончания воркшопа мы проверили свои показатели: мы получили 17 звезд и 8 forks, что прибавило нам оптимизма.
Мониторинг статуса
Комментарии по улучшению. Будьте милы, делитесь своим мнением и радуйтесь обратной связи.
Неизбежно появится тот, кто обнаружит баги после запуска вашего проекта. Удостоверьтесь в том, что вы ответите на все комментарии и учтете фидбек. Находиться в контакте с аудиторией является ключевым моментом получения отдачи от пользователей. Если вы получите рост с 30 до 40 звезд за короткий период (1-2 часа), значит ваш проект имеет отличный шанс стать трендом (естественно, данная информация касается алгоритмов работы трендов в GitHub).
Топ трендинг Flask-base среди репозиториев Python на Github после 24 часов
Наши достижения
- Проект вышел в топы для репозиториев python, 3 место в тренде и топ для /r/Python за неделю.
- Hack4Impact стал 4м топовым python-разработчиком и 5м среди всех разработчиков.
- Кроме этого, у нас более 80 клонов и 40 forks в настоящий момент.
Могу сказать, что это безумно приятное ощущение, когда ты видишь, что люди используют код, который ты помогал писать.
Письмо с благодарностью, полученное мной
Наша аналитика на GitHub. Reddit реально помог.
Если вы не смогли попасть в тренды, не отчаивайтесь. Просто встряхнитесь и повторите.
Всем иногда везет, а иногда нет.
Если вы предприняли попытку создать открытый исходный код, полезный для людей, вы и так уже вносите свой большой вклад в мир open source.
Поделиться с друзьями
dmitry_dvm
Зачем эти звездочки? Зачем быть в топе репозиториев? Я, видимо, чего-то не понимаю.
Alexeyco
Третья базовая потребность человека: доминирование
Areso
Возможно, это потребность в признании, уважении. Звездочки, форки, вотчи — это все виды признания.
Ну, а если стремиться стать абсолютным лидером по ним, то, пожалуй, да, это доминирование.
EverydayTools
Ну хотелось человеку, чтобы про его работу узнали.
search
Во-первых получить звёздочку на гитхабе чертовски приятно. Здорово, когда ты делаешь что-то нужное. Во-вторых это полезно для карьеры. Я недавно менял работу и многие работодатели очень хотели посмотреть мой аккаунт на гитхабе. Как-то так.
SurfCalavera
Для резюме скорее всего. Выше рейтинг проектов в которых участвовал — можно аргументировать цену повыше.
Это же наверняка не единственный его проект, есть и коммерческие.
reforms
Для меня, самая близкая аналогия — состояние, после публикации статьи на хабре, когда ты понимаешь, что затраченные усилия оказались ненапрасными, бонусом — разноцветный букет эмоций!
dom1n1k
Встречный вопрос: зачем тогда вообще что-то публиковать?
ValdikSS
Какой-то асимметричный вопрос. Код публикуют ради того, чтобы кто-то другой им воспользовался, а некоторые и вовсе используют github в качестве хранилища резервных копий. Я, например, использую звездочки на github в качестве закладок — отмечаю репозитории звездой для того, чтобы не потерять их. Это вовсе не означает, что мне нравится представленная в репозитории программа.
dom1n1k
Я тоже часто использую звездочки в качестве закладок. Это нормально и этого достаточно.
Не в самих звездочках дело, дело в понимании, что кому-то продукт пригодится или хотя бы заинтересовал.
Если нет никакого фидбека, то становится непонятным — а зачем вообще тратить столько усилий, которые уходят в черную дыру?
ValdikSS
Не уверен, что понимаю вашу мысль. Программы, вроде бы, в основном пишут для решения какой-то конкретной задачи, и, прежде всего, для себя. Под усилиями вы понимаете оформление коммитов, или что-то другое?
dom1n1k
1. Написал, решил задачу. Всегда ли нужно продолжать развивать?
2. Поддержание публичного репозитория в «красивом» виде требует несколько других усилий, чем внутреннего для себя.
ValdikSS
Я, пожалуй, не назову ни единого проекта, который бы выполнял пункт №1 только средствами сообщества, без материальной поддержки со стороны какой-либо корпорации или иного заинтересованного лица. В моем кругу общения нет разработчиков, которым есть дело до того, как их проекты будут использовать другие люди, и какая функциональность им может потребоваться.
Видимо, все люди разные, и я делаю все с точностью до наоборот: документирую собственные скрипты и программы тщательно, чтобы я мог через 3-5-10 лет вспомнить досконально, как это все работает, а публичным репозиториям предпочитаю писать краткое описание и инструкцию по быстрому запуску. Кого интересует код и так разберутся.spmbt
Ответ на этот вопрос скрыт в статье под спойлером со словами «реального мира».
Вот ключевые слова: «Внезапно мы начали получать комментарии и предложения от людей, которые были заинтересованы в нашем проекте, и это было превосходно.»
hlogeon
Когда у меня появились боле-менее серьезные контрибуции в open source, на меня магическим образом начали выходить работодатели немного другого уровня, выросла зарплата, появились связи с более крутыми разработчиками с разных уголков планеты. Вангую, что если бы я сделал какой-то проект с 200+ звездами на github все, что я перечислил произошло бы с намного большей силой.
Лучший способ доказать, что ты хороший разработчик — показать свою разработку. Лучший способ показать, что разработка нужная — показать число людей, которые ей пользуются. Лучший способ показать качество продукта — показать отзывы людей.
DnV
А вы уверены, что «работодатели немного другого уровня» выходят на вас именно через опенсорс, а не просто оценивают разросшееся портфолио?
hlogeon
Да, уверен. Всегда спрашиваю где и как меня нашли. И в последние годы слышу только: «Через github/stack overflow». Более того, я не допускаю «разростания» портфолио, удаляя неактульные работы, или работы, которые не имеют большого значения в моей карьере. Знаете, чем опытней становлюсь, тем короче становится мое CV.
vitalybaev
Подтверждаю, в прошлом году потихоньку начал контрибьютить небольшие патчи в проекты на GitHub. В итоге за последние 4 месяца пришло около 10 предложений о работе. Из них 3 связанных с переездом в страны Европы. Среди наших были и известные компании, вроде ABBYY, СберТех. Многие писали, что нашли мой профиль на GitHub
Antelle
markhor
Есть одна дурацкая причина. На количество звезд любят смотреть люди, далекие от IT. Инвесторы, рекрутеры и т.д. Для них число звезд == крутизна проекта. Хотя все давно поняли что число звезд == способность авторов пиарить (что в общем-то не плохо само по себе, но слабо коррелирует с качеством).
Если уж измерять популярность репозитория, то стоит это делать по числу уникальных клонов (Гитхаб к сожалению это не показывает публично), либо по количеству контрибьюторов и их крутизне. В последнем случае можно ввести PageRank и вообще упороться по математике (как я, см. статью).
KvanTTT
Неплохо вы постарались.
Возможно Гитхабу не хватает рейтинга как для человека, так и для отдельных репозиторий по аналогии со stackoverflow. Иногда испытываю необходимость в нем.
Deosis
Меня больше интересует, зачем делать больше 70 вилок?
Если есть улучшение, можно сделать пулл-реквест или ветку, если используется местные допиливания.
f0rk
Затем, что иногда нужно сделать изменение, которое нафиг не сдалось в апстриме, либо PR не хотят принимать (причин этому может быть куча), либо апстрим давно уже не поддерживается, а сделать изменение нужно. Есть много причин по которым может потребоваться форк.
PashaPodolsky
Чтобы сделать пулл-реквест, надо его сначала коммитом отправить в свой форк.
MockBeard
зачем артистам аплодисменты? зачем быть звездой?
люди делают интересное дело и получают признание полезности таким образом
magic4x
Я публиковал свои проекты на хабре. День, другой +- звезда, другая. Потом какой-то чувак запостил мой проект на медиуме и кто-то указал в комментах на реддите — пара сотен звезд за пару дней.
Логика, конечно же, простейшая: на реддите люд со всего мира. Очень приятно открыть список звезд и видеть такое разнообразие городов и стран, знать, что ты немного к этому причастен. Приятно пользоваться опенсорсом, не менее приятно сорсить самому.
Lockal
Не понимаю, зачем столько рассуждений про ридми, когда в топ вполне себе спокойно каждый день выходят "pure educational" проекты с plain-text описанием на одном лишь hacker news и реддите.
vics001
Скоро уже можно маркетинговый бюджет планировать на продвижение open-source проектов в github. Потом комиты с котятами постить, чтобы удержать подписчиков.
Antelle
Тут ещё хорошо написано, есть и про readme немного:
https://changelog.com/posts/top-ten-reasons-why-i-wont-use-your-open-source-project
график отсюда: http://www.timqian.com/star-history/
KvanTTT
Обычно действительно интересующиеся и активные люди все же добавляют проект в watch список. А star менее важны.
atoshin
README, ля-ля, тополя, запостили на reddit — оп-па, куча звёзд! Вывод — нафиг ваши ля-ля про README, постите сразу на reddit
DmitryLeonov
Статический анализ кода, статистический, какая фиг разница…
lucius
Внимание! Продвижение вашего репозитория на GitHub'e!
В результате вы получаете:
* Эффективное размещение в лучших базах HR агенств
* Поддержку при создании и форке репозиториев даже если у вас не было опыта работы с git
* Гарантированное увеличение количества звёздочек на ваших репозиториях
* Практически полную автоматизацию написание кода в ваших репозитория сообществом
* Экономию времени на просмотр пулреквестов на 87-90%
* Красивую золотую рамку вокруг аватарки
Areso
В каждой шутке есть доля шутки.
winger
Зачем замазывать reddit-аккаунт на скриншотах, если он гуглится по ним за минуту?
nezdhanov
Пост-воркшоп про воркшоп?
bevice
По тону статьи чувствуется посыл, «про нас никто не знал, и вот все узнали, и вот мы топе. Учитесь сынки». А по-факту — пост на reddit дал сиюминутный приток пользователей и всё. Вот прошел месяц, проект вылетел из топов (топу больше интересны производные, чем количество звезд).
Давайте вернемся в реальный мир, то, что описано в статье ерунда, за исключением поста на reddit. Ни огромный логотип, ни инструкция по-установке, ни воркшопы не принесут проекту популярности, разве что в какой-то мере могут её (популярность) поддержать.
Это видно по картинке с источниками переходов — народ повалил по ссылке с reddit, GitHub это заметил и положил проект в топ, еще какое-то количество человек пришло по ссылке из топа. И все. Ни форумов, ни stackoverflow. Люди пришли, посмотрели, тыкнули звезду (а вдруг пригодится) и ушли.
Чтобы проект стал популярным, нужно его каждый день пиарить, тогда при наборе некоторой критической массы начнет работать «сарафанное радио» и поток пользователей не будет угасать без рекламы.
Хотя, безусловно, хорошее оформление, документация и хороший код — это все очень важно и нужно.