[Перевод] Как двухлетний репозиторий на GitHub стал трендовым за 48 часов
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 осталась неизвестным в широких кругах, но стало полезным для людей, работающих с ней.
С чего мы начинали
Наши провальные попытки расширить аудиторию приводили к отчаянию, так как мы были уверены, что другие разработчики и небольшие компании могли бы использовать плод нашего труда для значимых проектов. Но мы никак не могли найти способ продвижения нашего продукта. В результате этого, мы подвергли сомнению честность источников с открытым исходным кодом, которые должны освещать отличные идеи для широкого круга потребителей.
То самое чувство
Впоследствии мы обнаружили ошибку нашего подхода. Мы внимательно изучили, каким образом работает открытый исходный код с точки зрения пользователя. Мы нашли ключевые области, которые нужно было пофиксить и усовершенствовали наш проект, чтобы он стал пригодным для
Внезапно мы начали получать комментарии и предложения от людей, которые были заинтересованы в нашем проекте, и это было превосходно.
прошлые дни += 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 and я проводим воркшоп по 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.
