Портфолио

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

Сергей

Речь о проектах Практикума?

Практикум

Да, именно них. Ваше портфолио уже на GitHub?

Сергей

Сейчас залью.

Готово! Проекты проверены ревьюерами, поэтому всё должно быть отлично.

Практикум

Точно? Кажется, кое-чего важного не хватает.

Сергей

Чего это не хватает?

Практикум

Захожу в репозиторий и не понимаю, что это за проект. Описания нет, про стек технологий ни слова... Ничего не понятно.

Сергей

Там же код же есть, в нём всё ясно!

Практикум

Если в портфолио зайдёт рекрутер — он ничего не поймёт и уйдёт разочарованным. А если зайдёт разработчик — он выругается про себя и, скорее всего, тоже не станет смотреть код: времени и так мало, а тут ещё в чужом коде копаться. Да ну.

Портфолио — это сборник ваших лучших работ, тех, которыми хочется похвастаться. Для учебного опыта — это практические работы: «Смотрите, как здорово у меня получилось во время обучения!» Может, проекты не очень сложны, но это действительно ваши лучшие работы.

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

Сергей

С документацией?! Вот прямо подробно всё расписать? Это обязательно?

Практикум

Обязательно. А степень подробности должна быть разумной, конечно.

Три важных правила про проекты на GitHub

Правило #1: Код без документации не имеет ценности

Сергей

Как так «не имеет ценности»? Код есть, проект работает...

Практикум

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

Пока описания проекта нет — разработчик является единственным носителем уникальной информации, и передать эту информацию другим он может только в личной беседе. Однако гораздо проще один раз описать проект, чем множество раз рассказывать о нём.

Сергей

Ну да, я первый проект уже не помню. Что там мы делали...

Практикум

Вооот! В таких ситуациях память — не самый надёжный друг, может подвести. А если будет сложный проект с участием нескольких разработчиков, с запутанной историей зависимостей и принятых решений?

Все должны понять задачи проекта, увидеть, где заканчиваются границы ответственности одного разработчика и начинаются задачи другого — как объяснить это без документации? Никак.

Сергей

Да, это прямо нужно.

Практикум

Отсюда второе важное правило: код на гитхабе — не только ваш.

Правило #2. Код пишется не для вас, а для других людей

Если код нужен только вам, то не обязательно его выкладывать на GitHub. Это не имеет особого смысла, кроме удобства хранения.

Если вы выложили код в публичном репозитории — этот код предназначен не только для вас, а и для рекрутера — чтобы показать ему ваши практические навыки, для тимлида-работодателя — чтобы он мог оценить ваш уровень hard skills, для коллег на новом месте — чтобы показать задачу, над которой вы трудитесь.

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

Сергей

Может, хватит и комментариев в самом коде? У меня тут как раз есть пометки.

Практикум

Нет, комментариев будет недостаточно даже для вас. Уже через год-два вам будет сложно восстановить картинку проекта. И по комментариям не всегда понятно, как запустить проект, какие там зависимости, в чем состоит функциональность. Тут напрашивается третье правило.

Правило #3. Документация — сборник информации о проекте

Документация — это единое информационное поле для всех участников проекта, от разработчика до технического директора.

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

Если все в голове держат одну картинку — будет проще вести проект.

Сергей

Да, это было на курсе бэкенда. README, верно?

Практикум

Да, на GitHub для этого есть файл README.md.

README — лицо вашего проекта

README для каждого проекта свой — добавляете его в корень папки проекта и ведёте там документирование.

Если в вашем профиле GitHub много проектов, с разной направленностью и стеком разработки, то в общей папке тоже должен быть README.md — для навигации по всем проектам: это показатель культуры разработчика.

Содержание README.md

Заголовок-название.
Описание проекта: его назначение, какую боль он закрывает, зачем вы его делали. Упражнялись с новой библиотекой — так и напишите. Здесь же можно указать стек, если используется много технологий разом. Это краткая презентация проекта. Не ограничивайтесь одним предложением и названием.
Инструкция по развёртыванию и системные требования (версия языка, зависимости). Сторонний разработчик по этой инструкции должен легко и без проблем запустить проект и убедиться, что он действительно работает.
Планы по доработке проекта, если они есть, и если вы их действительно осуществите. Не общее «сделать рефакторинг», а «исправить X с помощью Y, чтобы получить Z». Чем конкретнее — тем лучше.
Можно добавить ещё много всего: расширенную техническую документацию проекта; настройку CI для его запуска; список людей, которые над ним трудились.

Это уже касается уже крупных проектов, в учебных это не обязательно.

Сергей

А есть примеры, куда можно подсмотреть?

Практикум

Да, конечно!

Примеры

На GitHub есть целый раздел, в котором можно подсмотреть документацию различных опенсорс-проектов: https://github.com/explore. Готовые README — идеальный инструмент для документирования, их часто используют в открытой разработке.

Для Python выбираете подходящий topic и смотрите проекты:

Django framework — https://github.com/django/django
Flask framework — https://github.com/pallets/flask
Scrapy — https://github.com/scrapy/scrapy
А вот тут опенсорс-приложения для MacOS — https://github.com/serhii-londar/open-source-mac-os-apps
И ещё один пример списка проектов в проекте —Awesome Python https://github.com/vinta/awesome-python

Сергей

Да, с примерами всегда понятнее как-то.

Практикум

😉

Бонус: портфолио и рекрутеры

Рекрутеры тоже смотрят портфолио. Может не так внимательно, как разработчики, потому что не все умеют читать код. Но полезную информацию они оттуда точно вытягивают.

Вам будет полезно знать, на что рекрутер может обратить внимание.

Ваша активность на GitHub

Первое, на что обращают рекрутеры внимание — как часто вы совершаете действия на платформе (contribute). Эта информация доступна в мониторе активности любого разработчика.

За контрибуты считается активность в открытых репозиториях:

commit в мастер-ветку;
открытие issue;
предложение сделать pull request;
отправка pull request на проверку.

Сергей

А если я не веду GitHub?!

Практикум

Это не приговор. Возможно, вы — GitHub-социофоб, и все репозитории в вашем профиле закрытые. Много чего может быть. Не переживайте, рано или поздно рекрутер вас найдет, просто в другом месте.

Стек, с которым вы работаете

Да, рекрутеры смотрят, с какими языками программирования, фреймворками и другими инструментами работаете. Поэтому важно упоминания стека разработки в README.md, например.

Ещё обратите внимание на топики GitHub. Топики — это теги, метки для создания тематических связей между репозиториями GitHub. Они позволяют просматривать проекты по типу, технологиям и прочему. И находить разработчиков, у которых есть проекты с подходящими технологиями.

Укажите подходящие топики в своем проекте. Для этого справа в папке проекта найдите меню О проекте/About. Нажмите на значок настроек и добавьте Topics.

Это позволит не только рекрутерам, но и другим разработчикам найти вас по вашим проектам. Здесь тоже работает нетворкинг: кто-то из разработчиков подпишется на ваш профиль, кто-то поставит звёздочку вашему проекту, снежный ком дополнительных контактов начнёт расти.

Сергей

Прикольно! Теперь понятно, как проекты попадают в эти самые Toпики.

Практикум

Да, классная фича.

Про звёздочки и фолловеров

Звезда (star) — это способ подписаться на проект и отметить интерес к нему. Так разработчики составляют для себя ленту по интересам, чтобы в будущем видеть больше подобных проектов.

Если у репозитория больше 500 звезд, то он, скорее всего, популярный и значимый. У Awesome Python, например, 90k звездочек.

Число подписчиков профиля — тоже косвенный индикатор вашей навыков и репутации в сообществе.

Что для рекрутера означают эти цифры:

2-10 подписчиков — нормально, 11-25 — хорошо, 26-75 — уже фантастика, а больше 75 подписчиков — это уже товарищ-рок-звезда.

Сергей

Каждая мелкая кнопка — какая-то фича! Иногда даже полезная.

Практикум

Да-да. А вообще посмотрите обзоры по использованию GitHub по типу того, что сделал 2ГИС на Хабре. Очень полезно!

Чеклист по облагораживанию репозиториев

Проверьте состояние вашего репозитория по этому списку.

Добавить контакты в профайл на GitHub (желательно — почту и Телеграм).
Проверить, что проекты работают и выполняют базовые заложенные в них функции.
Проверить, нет ли в коде лишних комментариев (особенно от код-ревьюеров).
Оформить Readme для каждого проекта:
- заголовок;
- описание;
- инструкция по развёртыванию/использованию (или ссылку, если это действующий веб-проект);
- системные требования (версия языка, зависимости);
- планы по доработке (если есть);
- стек технологий (в случае, если применено более двух инструментов);
- для крупных проектов;
  - расширенную техническую документацию;
  - настройку CI для его запуска;
  - список создателей проекта.
Пройти в реальности процесс развёртывания, сопоставить реальный процесс с инструкцией, проверить правильность работы проекта.

Всё готово, вы великолепны!

Проверка работы

Если вы считаете, что портфолио готово:

Убедитесь, что все ваши репозитории в профиле GitHub открыты.
Перейдите по ссылке на Яндекс.Форму.
Укажите ваши фамилию, имя и номер учебного потока. Этот номер можно узнать в названии учебного канала в Slack.
Добавьте ссылку на ваш профиль GitHub.
Ревьюер вернётся с обратной связью в течение недели в личном сообщении в Slack.