Почему я не использую ваш репозиторий GitHub

pochemu ya ne ispolzuyu vash repozitorij github?v=1656537138

Сэм Вестрейх, доктор философии

SUgIS8DAQAs7M4mWjsgStAJW7YCsQSXC3vdl
Ваше плохое управление репозиторией Github разочаровало этого кота. Вы сделали это. Фото: FuYong Hua.

Как биоинформтик, я нахожусь в интересной середине между разработчиками и конечными пользователями. Моя базовая подготовка – биология, а не информатика.

Но в последние годы биология приблизилась к информатике. Многие типы биологических данных слишком велики, чтобы их анализировать вручную, и их необходимо обрабатывать с помощью компьютеров. Постоянно понижающая стоимость генома секвенирования привела к появлению огромного количества данных о последовательности. Все эти данные необходимо собрать, сравнить, искать и комментировать.

Все больше и больше биологам нужны компьютеры.

Вернее, биологам нужны компьютерные программы. Посмотрите, если у меня есть куча данных о последовательности микробиома, которые я хочу сопоставить с разными видами происхождения, я не собираюсь садиться и создавать свой инструмент для выравнивания с нуля. Я собираюсь взять готовый цифровой инструмент, который использовался раньше, помолюсь, чтобы его было достаточно просто установить и подключу его.

В аспирантуре я совершил ошибку. Я позволил быстрому темпу компьютерного мира соблазнить меня. «Больше никаких недельных экспериментов в лаборатории!» – заявил я себе. «Я собираюсь с головой окунуться в компьютерную сторону биологии и стать мостом между обоими мирами. биоинформатик!”

Теоретически биоинформатик анализирует данные, собранные биологами, открывая новые выводы и налаживая новые связи.

На практике биоинформтик устанавливает множество программ и проклинает создавших их разработчиков.

Я отказался от многих программ — некоторые из которых, я предполагаю, очень хороши — из-за нелепых инструкций, плохого кода или ужасной документации.

Это дошло до того момента, когда я могу заглянуть в репозиторий GitHub и понять, как я отношусь к вашему инструменту.

Некоторые репозитории вселяют уверенность. Другие наполняют меня ужасом.

Иногда я считаю, что один так плох, что я отказываюсь даже пытаться установить инструмент (если этого не требует мой начальник).

Вот самые большие проблемы, которые я вижу, и как их избежать.

Причина 1: нет документов

1zjiS85MIpXdcMtpIlG0S-y71a8qsl74iaFH
Никто не знает, как использовать вашу программу, если вы не напишете ее для них. Фото Беатрис Перес Мойя.

Я видел все варианты документации:

  • Документация, написанная в Readme.
  • «Быстрые инструкции» в Readme с подробной информацией в отдельном документе PDF или Word.
  • Ссылки на вики GitHub.
  • Ссылка на внешний сайт с написанной там документацией.
  • Ссылка на внешний сайт, где есть еще одна ссылка для загрузки PDF-файла. (Почему просто не поместить PDF-файл в репо?)
  • Хуже всего… нет документации.

Да, я знаю, что писать документацию – это ужасно. Я создал конвейеры и инструменты и заставил себя писать документацию. Я забыл о крайних случаях и деталях команд, и иногда получал смущенные напоминания от пользователей.

Если вы создаете инструмент и делаете его общедоступным, ваша документация должна содержать по крайней мере:

  1. Требования и зависимости для использования вашего инструмента. Это включает как требования к аппаратному обеспечению (ОЗУ и размер диска), так и требования к программному обеспечению (операционная система, другие программы).
  2. Как установить инструмент |
  3. Что делает инструмент.
  4. Как заставить инструмент выполнять эти действия с помощью примеров команд.

Я также очень рекомендую вам включить:

  1. Раздел «частые вопросы».
  2. Тесты — это тестовые данные и точные команды, которые следует использовать для этих тестовых данных (до уровня, на котором команды следует скопировать/вставить в командную строку).
  3. Примеры выхода.
  4. Лицензия.
  5. Скриншоты, если есть.
  6. Благодарности, открыты ли вы к запросам на удаление, и контактная информация, чтобы пользователи могли сообщать о проблемах.

Плохая или неполная документация – причина номер один, почему я перестаю использовать инструмент. Вы знаете, как работает ваш инструмент, но никто другой не знает – не заставляйте людей разбираться в этом. Дайте четкие и простые инструкции.

Причина 2: от зависимости

FDURQPsceanAj4o0NmU9zlxk3jSqxqlwirie
«Каждое из них является зависимостью. Обязательно распакуйте их все в правильном порядке!» Фото chuttersnap.

Однажды я нашел инструмент (конвейер для аннотации последовательности ДНК), у которого было шесть зависимостей.

«Это не самое плохое», — подумал я о себе. «Я могу справиться с установлением шести зависимостей, чтобы использовать этот инструмент».

К сожалению, большинство из этих зависимостей имели другие зависимости. И у тех было еще больше зависимостей, в том числе некоторые, которые отказывались хорошо играть друг с другом.

К тому времени, когда я отказался от этого оригинального инструмента, я встретил девятнадцать различных зависимостей, которые мне нужно было установить, специально для использования этого единственного конвейера. девятнадцать!

Прекрасно, что существует много полезных инструментов, которые могут служить строительными блоками для более сложных программ. Гораздо лучше использовать уже существующую, признанную зависимость, чем изобретать велосипед и делать все самостоятельно.

Но если вы пойдете по этому пути, пожалуйста, найдите мне более простой способ установить зависимости для вашего инструмента.

Дайте мне скрипт установки, который я могу запустить, чтобы получить все зависимости — это особенно хорошо работает, если мне нужно полдюжины пакетов Python или R. Если возможно, дайте мне архив зависимости, чтобы мне не нужно было искать ее (при условии, что лицензия в зависимости позволяет такой уровень перераспределения).

Не втягивайте меня в ад зависимостей или, если вы это сделаете, будьте готовы к тому, что многие пользователи откажутся от использования вашей программы. Никто не хочет проводить время в аду.

Причина 3: проблемы с оставлением

KhyADvIhU0dygAeG6bMFeH4ECrYEia3ciQ8v
«Никто не обновлял это репо в течение долгого и долгого времени». Фото Натана Райта.

Когда проект GitHub новый и свежий, проблем не возникает. Он новый, чистый, и еще никто не нашел ошибки.

В течение следующих нескольких недель или месяцев, когда пользователи найдут приложение и испытают его, они будут поднимать проблемы. К счастью, GitHub имеет страницу в каждом хранилище, посвященную регистрации этих проблем. Это называется «Проблемы».

Здесь, на этой странице, пользователи комментируют, что они получают уведомление об ошибке при выполнении различных задач. Иногда это устаревшая зависимость. Иногда это ошибка в коде. Иногда это ошибка пользователя – у них неправильная версия другого инструмента, их ввод в неправильном формате или они используют незаконные параметры и не читают справочные сообщения.

На вид это отличная особенность. Но эта страница проблем также может быть предупреждением или сдерживающим фактором.

Страница проблем может вызвать один из двух красных флажков или зеленый флажок:

  • Красное знамя 1: проблем нет. Проблем никогда не было. Этим инструментом никто никогда не пользовался, он брошен и пылится.
  • Красное знамя 2: Есть несколько открытых проблем, в основном по ошибкам, без решения от владельца репо. Этот инструмент заброшен и сломан, и владельцу безразлично.
  • Зеленый флажок: открытых проблем очень мало, большинство из которых обозначены как улучшение, но многие закрытые вопросы. Владелец активно исправляет ошибки, помогает пользователям и планирует добавить больше функций.

Поскольку я публиковал приложения на GitHub, я знаю, что поддерживать их не очень весело. Приятно создавать что-нибудь новое. Неинтересно исправлять странные сообщения об ошибках и тупых случаях использования. Неинтересно переливать страницы старого кода и выяснять, почему суперспецифическое условие приводит к сбою.

Но самые лучшие программы (и самые надежные репозитории GitHub) созданы от создателей, которые готовы выполнять скучную работу. Это включает в себя решение проблем и оказание поддержки пользователям.

И если появятся ответы на другие вопросы, я чувствую себя увереннее, что мои собственные проблемы будут решены, и я смогу уверенно использовать инструмент в своих целях.

Продайте мне свою программу

8EDMTIs25bBgemnT6mDTYz25kR-hn81Wk3yP

Нравится вам это или нет, но ваш репозиторий GitHub часто является «лицом» программы. Ваше репо должно продавать вашу программу как простую в установке, легком запуске и легком понимании.

Великолепный репозиторий GitHub – это прекрасная вещь. Мне как неквалифицированному пользователю нравится, когда файл readme указывает мне, какие именно команды нужно установить инструмент, как им пользоваться и как устранить самые распространенные проблемы. Подробное и понятное руководство вызывает улыбку на моем лице. Одношаговый сценарий установления зависимости заставляет меня вздохнуть с облегчением. Признаки того, что вы поддерживаете свой инструмент и исправляете ошибки, заставляют мою грудь наполняться уверенностью.

Позвольте мне воспользоваться инструментом.

Позвольте мне процитировать вашу работу и спеть вас своим коллегам.

Позвольте мне уважать вас и отличную программу, которую вы создали.

Избегайте этих проблем — и избегайте этих ошибок в следующем общедоступном хранилище GitHub.

Сэм Вестрейх – ученый из микробиомы, работающий в Силиконовой долине, и провел годы, погружаясь в науку и ботанические занятия. Он ведет блог о науке, биологии, микробах и микробиомах, а также своих мнениях об аспирантуре и достижениях успеха.

Добавить комментарий

Ваш адрес email не будет опубликован.