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