README проекта хакатона: как объяснить запуск и ограничения
Что включить в README хакатонного проекта: установка, настройки, тестовые данные, сценарий демо и ограничения. Проверяем инструкцию на другом ноутбуке.
Репозиторий открывается, но проект не запускается: непонятна версия среды, отсутствует файл настроек, база пустая. Для автора это несколько привычных действий. Для другого участника или члена жюри работа останавливается ещё до первого экрана. README должен провести человека от ссылки на код до результата, который команда обещала показать.
Пишите инструкцию одновременно с первым запуском на новом компьютере. Тогда в ней появятся реальные зависимости, а не восстановленная по памяти последовательность. Описание архитектуры пригодится позже; сейчас читателю нужно понять, что он запускает, какие условия нужны и как убедиться, что всё получилось.
Начните с назначения и состояния проекта
Первый абзац отвечает на один вопрос: какую задачу решает прототип. Например: «Сервис помогает координатору распределить заявки по свободным волонтёрам. В демо используются вымышленные заявки». Это учебный пример формулировки, а не описание действующего продукта Stavleak.
Сразу ниже поставьте ссылку на доступное демо и укажите состояние проекта: хакатонный прототип, дата проверенной сборки, ограничения доступа. Если сервер выключен после финала, обновите этот блок. Мёртвая ссылка без объяснения заставляет читателя искать ошибку у себя.
Документация GitHub о README выделяет назначение проекта, начало работы, получение помощи и сведения об авторах. Для хакатона эту основу удобно дополнить проверяемым сценарием и честным списком незавершённых частей.
Запишите один воспроизводимый путь запуска
Не смешивайте в одной последовательности локальную разработку, развёртывание сервера и сборку мобильного приложения. Выберите основной путь для проверки. Остальные варианты вынесите ниже и обозначьте, кем они проверены.
Перед командами перечислите необходимые версии среды и пакетного менеджера. Затем укажите рабочую папку, установку зависимостей, подготовку настроек, создание тестовых данных и запуск. Если команда выполняется из подкаталога, напишите это рядом. Читатель не должен угадывать, где находится терминал автора.
После каждого существенного шага дайте короткий признак успеха. Например: открывается локальный адрес, появляется тестовая заявка, статус подключения меняется на доступный. Сообщение «готово» без проверяемого результата мало помогает при частичной ошибке.
Не вставляйте универсальные команды, которые не запускали именно в этом репозитории. Если проект требует ручной настройки стороннего кабинета, опишите её отдельно. Автоматическая установка библиотек не создаст чужой аккаунт и не выдаст ему необходимые права.
Объясните настройки без публикации секретов
Положите рядом пример файла настроек с названиями переменных и безопасными заглушками. Для каждой переменной укажите назначение, обязательность и источник значения. Разделите публичный адрес сервиса и секрет, который используется только на сервере.
Для проверки лучше подготовить отдельные демонстрационные данные. В README опишите, как их загрузить и вернуть начальное состояние. Не используйте в примере личные контакты участников, рабочие токены команды или реальные клиентские документы.
Если без платного или закрытого сервиса запуск невозможен, скажите об этом до установки. Предложите доступную запись демо либо отдельный демонстрационный режим, если он действительно реализован. Не называйте заглушку полноценной интеграцией.
Дайте читателю контрольный сценарий
Короткая инструкция проверки может состоять из пяти действий:
- Открыть стартовую страницу и выбрать демонстрационный профиль.
- Создать заявку с указанными тестовыми параметрами.
- Запустить обработку и дождаться изменения статуса.
- Открыть результат и сравнить его с описанным ожиданием.
- Сбросить тестовые данные перед следующей проверкой.
Подстройте этот порядок под свой продукт. Для модели это может быть обработка одного файла, для устройства подключение датчика, для инструмента разработчика запуск команды. Смысл проверки должен оставаться понятным человеку, который не присутствовал на вашей презентации.
Отдельно назовите ограничения: один поддерживаемый формат, отсутствие восстановления пароля, ручная подготовка данных. Укажите, какие части работают, какие показаны макетом и какие остались планом. Это экономит время на обсуждении с жюри и будущими участниками проекта.
Проверьте документ без помощи автора
Попросите товарища открыть чистую копию репозитория и выполнить шаги. Во время проверки не подсказывайте устно. Записывайте места, где потребовалось вмешательство, затем исправляйте инструкцию или сам запуск. Если человек застрял на втором шаге, красивое описание технологий ниже не компенсирует этот пробел.
Перед сдачей сопоставьте README с зафиксированной версией кода. Проверьте ссылки, имена файлов и доступ к демонстрации. Организацию общей версии разбирает материал о Git для команды хакатона, а проверку внешнего адреса продолжает руководство по деплою прототипа.
Проверьте, что README закрывает требования конкретного события. Найдите его страницу в каталоге Stavleak и сверьте комплект сдаваемых материалов.
