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