Описание проекта, из-за которого его хочется открыть

Зачем оно нужно

Описание в корне репозитория — первое, что видит человек. Если его нет или оно пустое, код чаще всего просто не смотрят: непонятно, что это, зачем и как запускать.

Это самая дешёвая правка в портфолио: полчаса работы, а разница в том, откроют ваш проект или закроют, огромная.

Что писать, по порядку

1. Что это, одним абзацем. По-человечески, без терминов. «Сервис, который считает расходы по фотографиям чеков: загружаешь снимок, сумма попадает в месячный отчёт».

Проверка: поймёт ли человек, далёкий от вашей области.

2. Ссылка, где посмотреть. Работающая. Сразу вверху, а не в конце.

3. Скриншот или короткая запись экрана. Одна картинка объясняет больше трёх абзацев. Особенно если есть интерфейс.

4. Как запустить. Команды, которые правда работают на чистой машине. Проверьте на другом устройстве — почти всегда что-нибудь забыто.

5. Из чего сделано. Технологии и коротко, почему выбраны такие. Второе важнее первого: выбор с обоснованием показывает, что вы думали.

6. Что внутри устроено. Пара абзацев про то, как всё связано. Нужно, чтобы человек не гадал, с какого файла начинать.

7. Что дальше. Чего не хватает, что планируете. Этот пункт часто пропускают, а он показывает, что вы видите слабые места собственной работы. Ценится.

Чего не надо

• Копии документации используемых библиотек.
• Пустых заголовков, оставшихся от заготовки.
• Хвастовства. «Уникальный сервис, не имеющий аналогов» вызывает обратный эффект.
• Простыни на десять экранов. Читают первые два.

Про командные проекты

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

Формулировка простая: «Иван — данные и обработка, Мария — интерфейс, Пётр — развёртывание и сборка». Одна строка, которая снимает главный вопрос к любому командному проекту.

Ещё лучше, когда вклад участников описан не ими самими, а тем, кто вёл проект: тогда это уже не самопрезентация, а свидетельство.