Люди делают проекты, размещают их на GitHub, рассчитывают на обратную связь, на интерес. И очень обидно, когда явно видно, что ваш репозиторий никому не интересен, нет ни просмотров, ни отзывов, никакой другой реакции. Как будто вы выкладываете проекты в пустоту. Почему так бывает? Очень может быть, что вы при публикациях допускаете важные ошибки. Но для начала напомним, что такое GitHub и какая от него польза.
GitHub – это веб-платформа для управления версиями, которая позволяет разработчикам программ работать совместно. Ресурс стал основой для принципиально нового подхода специалистов в области IT к работе.
На сегодняшний день GitHub – самый популярный сервис кодового хостинга и самое крупное веб хранилище программных решений. Здесь нашли свое начало известнейшие стартапы, здесь размещены некоторые коды решений Google, Amazon и Facebook.
При этом важно понимать, что ГитХаб нельзя воспринимать просто как инструмент для совместной работы программистов. Это сетевой ресурс, где разработчики выставляют свои проекты и одновременно могут черпать информацию из чужих работ. Таким образом, здесь всегда можно найти нечто нужное, новое, а также поделиться своими разработками и, в результате, повысить свою профессиональную репутацию.
К людям с высокими рейтингами на GitHub, чаще обращаются за помощью и предлагают работу представители IT-компаний. Т.е. собственный репозиторий на GitHub – это одновременно и возможность найти решение сложной задачи, и профессиональная рекламная площадка, где вы продвигаете себя как специалиста.
Как бы то ни было, если ваш репозиторий «не работает», ему чего-то не хватает. Приведем наиболее часто допускаемые ошибки.
Описание проекта: зачем это нужно?
Важно понимать, что пользователи – ленивы, разбираться, зачем нужен ваш проект, в чем его преимущества, и подойдет ли он им по функционалу, людям обычно не интересно. Кое-что они могут понять из названия, но ведь далеко не все, верно?
И если у человека не будет уверенности (или хотя бы серьезных надежд), что ваш проект поможет ему решить свой вопрос, никто не пойдет изучать документацию или, тем более, код. Тем более, что скорей всего, рядом лежит множество аналогичных проектов, соответствие которых запросу – очевидно.
В чем дело? Проекты-конкуренты имеют краткое, но информативное описение. Подумайте, чем конкретно Ваш проект выделяется среди аналогов. Опишите его важные особенности и преимущества. Расскажите кратко и понятно: что он может делать и почему это решение интереснее конкурентов. Помните, что одна из важных задач вашего репозитория GitHub– продвигать и продавать проект и ваши навыки. Если вы сами не обоснуете, почему именно данное решение является нужным и интересным, вряд ли это сделает кто-то другой.
Как сделать красивое описание
Почитайте, как пишут ваши коллеги. Подумайте еще раз: какое из преимуществ – самое важное. Его нужно указать в 1-2 предложении. А если есть такая возможность, даже включить в заголовок.
Помните: текст описание должен быть небольшим, так как пользователи не будут читать длинные статьи, им нужен краткий, информативный анонс. При этом постарайтесь, чтобы текст был простым для восприятия и понятным максимально широкому кругу читателей.
Если для вас хорошее описание – проблема, составьте его в свободной форме и обратитесь к копирайтеру. Не так и дорого – написать небольшой анонс. Зато текст будет привлекать внимание. Аналогично стоит пользоваться услугами переводчиков, если вы не уверены в своем знании английского языка. Не стоит экономить на своей репутации и возможности повысить популярность проекта.
Не злоупотребляйте зависимостями
Наглядно проблему описывает широко известная история от одного из программистов на Stack Overflow. Он рассказывал, как взялся однажды за изучение программного решения, в котором сразу увидел шесть зависимостей. Будучи уверен в своих силах, он намеревался их легко обработать. В процессе разработчик понял, что к каждой зависимости привязаны следующие. К тому моменту, когда ему надоело пытаться разобраться с продолженным кодом, он успел найти около двадцати зависимостей.
Так вот, не придумывайте новые зависимости. Используйте готовые или вовсе их избегайте. Альтернатива – предоставить инструкцию, которая поможет быстро увидеть и изучить все существующие зависимости. Это довольно легко сделать в Python и R.
Документация должна быть доступна и подробна
Запомните: пользовательская документация — это «входная дверь» в ваш проект. Чем доступнее она будет, тем больше пользователей доберутся до сути вашей работы.
Многие IT-шники не любят работать с документацией. А потому нередко хорошие проекты сопровождаются такими вариантами:
- Файл Readme;
- Небольшое ознакомление в Readme плюс ссылка на документацию в формате PDF;
- Указание wiki-страницы GitHub ссылкой;
- Ссылка на сайт с официальными документами.
Это, конечно, лучше, чем полное отсутствие документации. Но все равно маловато.
При создании документов мы рекомендуем обязательно включать такие пункты:
- Перечень системных требований (постарайтесь сделать его максимально подробным).
- Функциональность: описание возможностей и задач, которые решает продукт.
- Инструкции по установке и запуску.
- Руководство пользователя с примерами и скриншотами.
Кроме того, очень полезно выложить:
- Частые вопросы (FAQ) с вашими ответами.
- Инструкции разработчику: как протестировать качество работы, проверка результатов через командную строку и т.д.
- Текст лицензионного соглашения.
- Контакты.
Неполная или сложная для восприятия документация – одна из самых распространенных причин, по которой пользователи бросают идею изучения того или иного, пусть даже хорошего, решения. Человек не хочет тратить время на преодоление очевидных сложностей, тем более, что альтернатива чаще всего «лежит» рядом.
Исправляйте баги и выпускайте обновления
Если GitHub-проект свежий, оснащен хорошим описанием и необходимой документацией, при этом в нем нет видимых багов, вероятность интереса к нему высока.
Но через какое-то время после публикации находятся изъяны и уязвимости, и их нужно незамедлительно закрывать. Тем более, что список таких проблем по любому из проектов виден всем посетителям.
Это могут быть выявленные уязвимости и баги, опечатки в коде и проблемы с доступом, логические и любые другие ошибки.
С одной стороны, это очень удобно, так как разработчик может быстро увидеть все выявленные баги и уязвимости. С другой стороны, весь этот перечень ошибок видит любой посетитель. Именно сюда заглядывает большинство пользователей ГитХаба, чтобы определить «сырость» решения.
Конечно, каждому программисту интереснее заниматься решением новой задачи, а поддержка, поиск багов, исправление старого кода мало у кого вызывают энтузиазм. Но делать это необходимо. Помните, что наиболее успешные стартапы – результат монотонного труда и постоянного сотрудничества с пользователями.
И последнее: а так ли вы хороши?
Если вы все делаете, вроде бы верно, но ваши решения все равно не привлекают интереса или вызывают негатив, стоит всерьез подумать: может быть вам просто рано показывать свои достижения, а нужно немного еще поучиться?
Некоторые программисты, особенно из числа молодых людей, склонны переоценивать свои таланты. И выкладывают в репозитарии действительно никому не нужный код, вы тысячный раз дублирующих существующие решения, зачастую, не самым удачным образом.
Не спешите показывать свои таланты. Посмотрите, что предлагают другие, как работают с ГитХабом ваши коллеги, изучите возможности проекта. Помните: опыт вы наработаете, знания получите, а вот репутация – вещь крайне хрупкая. И если вы попадете в списки «говнокодеров», доказать обратное будет не так просто. Не спешите к славе и монетизации своих решений – убедитесь, что вам и правда есть чем поделиться с коллегами.
[customscript]techrocks_custom_after_post_html[/customscript]
[customscript]techrocks_custom_script[/customscript]
