Зачем вообще люди пользуются GitHub? Потому что это социальная сеть, которая полностью изменила подход IT-специалистов к работе. Сейчас, GitHub является крупнейшим онлайн-хранилищем проектов, и именно здесь зародились многие известные стартапы. Более того, здесь можно найти код проектов таких компаний, как Google, Amazon, Facebook.
Одно из главных заблуждений о GitHub заключается в том, что это инструмент разработки. На деле же это больше соцсеть, в которой вы делитесь своими проектами, смотрите чужие и таким образом удовлетворяете свои потребности в поиске нового и повышении репутации.
В любом случае, если репозитории, которыми вы управляете, не пользуются спросом, возможно, им чего-то недостает. Рассмотрим распространенные ошибки создателей GitHub-проектов.
Часто документация реализуется следующими способами:
- Запись в Readme
- Короткий гайд в Readme со ссылкой на полный документ в PDF
- Ссылка на вики-страницу GitHub
- Ссылка на внешний сайт с файлом документации
И хуже всего − когда её просто нет.
Да, понятно, что документация, созданная непрофессионалами, часто выглядит ужасно, но без неё будет ещё труднее. Вот некоторые моменты, которые нужно включить в документ:
- Системные требования, без которых лучше не пользоваться разработанными инструментами. Здесь следует указать параметры ОЗУ, размера диска, версии ОС и другие критически важные данные.
- Гайд по безопасной установке.
- Обзор функций и возможностей.
- Инструкция по использованию и примеры решения задач, с помощью возможностей программы.
Кроме вышеперечисленного, неплохо было бы включить в список:
- Ответы на часто задаваемые вопросы.
- Инструкцию, которая поможет проверить, правильно ли установлена программа. Пользователь должен иметь возможность протестировать работоспособность с помощью командной строки.
- Примеры вывода.
- Лицензионное соглашение.
- Скриншоты, если они могут понадобиться.
- Контактную информацию.
Плохая или неполная документация − первая причина, по которой многие перестают использовать инструмент. Никому не хочется тратить время на то, чтобы разобраться, как работает та или иная кнопка, если проще скачать другую, интуитивно-понятную программу.
Известный разработчик на Stack Overflow рассказывал, что однажды ему попалось ПО с шестью зависимостями, но он не придал этому значения, решив, что сможет их обработать. Позднее выяснилось, что каждая зависимость содержит другие, как матрёшки. К тому моменту, как ему надоело изучать этот инструмент, он обнаружил более девятнадцати зависимостей. А ведь от инструмента было нужно совсем немного.
Не нужно придумывать свои зависимости: лучше брать готовые. Или избавляться от них вообще. Либо поделитесь инструкцией, которая поможет обнаружить сразу все зависимости, тем более что в Python и R это реализуется достаточно просто.
Когда GitHub-проект свежий, пользоваться инструментом приятно, если он, конечно, без багов. Если в течение некоторого времени после релиза обнаруживаются уязвимости, то закрывать их нужно как можно скорее, тем более что в каждом репозитории есть специальный раздел с проблемами.
Недочётами могут быть устаревшие зависимости, опечатки в коде, пользовательские ошибки, проблемы с доступом. Так что, с одной стороны, это крайне полезно, что проблемы собираются в одном месте. С другой, перед установкой инструмента пользователи могут проверить с помощью него, насколько сырой продукт.
Понятно, что поддержка старых проектов и устранение багов менее приятное дело, чем разработка чего-то нового. Но лучшие продукты получаются у тех, кто готов к выполнению скучной работы и взаимодействию с пользователями для решения их проблем.
Это уже не проблема, но совет: коротко обоснуйте, зачем ваш проект нужен, и чем он выделяется среди сотен других. Сейчас основная масса проектов не содержит информацию о практическом применении. Нравится вам это или нет, ваш репозиторий GitHub часто является «лицом» вашей программы. Репозиторий должен продавать эту программу.
Будьте уверены, что ваша работа действительно нужна, только убедите в этом остальных − они хотят использовать это, но не знают зачем.