Всех приветствую. Недавно в голову пришла идея и я начал заниматься очередным пет-проектом, и вот пройдя уже какую-то начальную стадию, дошел до необходимости его оформления, и понял, что вновь буду проходить через то, что проходил совсем недавно с другим пет-проектом, который я уже довел до какой-то логической точки. Подумал почему бы не сформировать этот опыт в статью и не поделиться ей.

Итак, начнем с простого, зачем оформлять пет-проекты? Если вы, как и я раньше, наивно полагаете, что потенциальные рекрутеры или юзеры (зависит от цели вашего пет-проекта, делаете вы его как демонстрацию ваших навыков или как какой-то продукт, но это не принципиально) будут пытаться понять суть вашего проекта по неоднозначному названию и паре строк в readme файле, то вы сильно ошибаетесь, а если вы думаете, что они станут читать код такого проекта, то ошибаетесь вдвойне. Именно поэтому пет-проектам нужно правильное оформление. Но что же в него входит? Что же, обо всем по порядку:

1. Название

   Конечно же чем понятнее и однозначнее название, тем лучше, однако, часто бывает такое, что мы уже создали проект и задумались о названии лишь спустя какое-то время, когда изменять везде название (и связанные с ним вещи) накладно или просто лень, либо же когда вы оформляете какой-то старый проект, поэтому этот пункт хоть и важный, но думаю не критичный. И я имею ввиду не только название проекта в гите, заголовок в readme файле, но и название проекта в коде, и связанные с ним вещи (такие как package в java, например, потому что не совсем красивые package, например, потом вам же самим будут доставлять эстетический дискомфорт).

2. README.md (Описание)

   Дальнейшие пункты все будут так или иначе связаны с файлом readme, однако для простоты чтения я буду оформлять их отдельными пунктами. И первый из них описание. Я не буду вдаваться в синтаксис md и советовать как именно выстроить структуру файла.

   Однако, очевидно, что все пункты следует выделить каким-то образом, например **жирным шрифтом**, чтобы отслеживалась структура. Касательно содержания конкретно пункта "Описание", я рекомендую оставить его кратким, но достаточно описывающим суть проекта, не стоит вдаваться в детали, потому что они будут расписаны подробнее в следующих пунктах.

3. Стэк технологий/Структура проекта

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

   Очевидно, присутствие стэка поможет потенциальным рекрутерам понять и оценить ваш проект, насколько он интересен в контексте вакансии. Структура проекта может помочь потенциальным юзерам и тем, кто будет смотреть в код, быстрее в нем соориентироваться. Я рекомендую не оставлять сразу оба пункта, а оставить тот, который для вас приоритетнее, а менее приоритетный скрыть спойлером.

   Делается это следующим образом: <details><summary><b>Структура</b></summary>...</details> (не забываем, что в md файлах работает и html , а поддержка спойлеров - отдельная фишка GitHub, md по дефолту, например, их не поддерживает).

4. Скриншоты

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

   Почему бы не хранить их на хостинге? Можно и на хостинге, но, честно говоря, по-моему опыту работы с ними, спустя какое-то время картинка может бесследно исчезнуть, и если вы не сохранили ее куда-либо, то вам придется заново делать скриншоты, что, наверное, не очень приятно.

   Касательно их оформления, обязательно спрятать их под спойлеры, ведь иначе readme получится очень длинным, что не очень приятно для глаза. Во-вторых, я рекомендую оформить их в качестве таблицы, а сами картинки хранить отдельно в папке /pictures, например. Итого у вас получится примерно такая разметка и результат, вроде выглядит неплохо:

   

   <details><summary><b>Скриншоты:</b></summary>
| ![Main page](/pictures/1.jpg "Main page") | | :--: | | *Main page* |
...
| ![Swagger](/pictures/5.jpg "Swagger") | | *Swagger* |
</details>

5. Мануал по запуску/использованию

   Вот мы и подошли, пожалуй, к одному из самых важных пунктов. Не раз я видел проекты, у которых худо бедно было какое-то описание, но абсолютно никаких инструкций по запуску/использованию. Конечно, вы можете надеяться, что рекрутер/пользователь пойдет сам разбираться и смотреть код, но я думаю, вы прекрасно понимаете, что это маловероятно. Именно поэтому это очень важный пункт.
   И так, что же здесь должно быть? Как минимум минимальный гайд по тому, как запустить ваш проект тому, кто хочет использовать его локально (или как подключить/использовать ваш проект, если это библиотека, консольная утилита и т.д.). Но и на этом не все.

   Если вашему проекту для локального запуска необходимы вспомогательные сервисы, например, конкретная база данных или sso, то, очевидно, глупо предполагать, что у кого-то они уже будут стоять, к тому же настроенные под ваш проект. Именно поэтому важно создать какой-нибудь docker-compose файлик, в котором настроить запуск необходимых вам сервисов, с необходимой настройкой (например, если в бд вам нужно инициализировать какую-то схему, использовать каких-то конкретных юзеров в sso и т.д.). Благо это можно сделать, в крайнем случае можно использовать dockerfile для настройки конкретно вашего image и его уже использовать в compose. Например, инициализация БД с нужными вам данными:

   services:
postgres:
image: 'postgres:14-alpine'
container_name: postgres
ports:
- "5432:5432"
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
POSTGRES_DB: postgres
volumes:
- ./imports/init.sql:/docker-entrypoint-initdb.d/init.sql

   Также можно дополнительно добавить второй файлик, который будет запускать также и ваши проекты, но это уже по желанию и в зависимости от вашего языка, насколько просто человеку будет запустить сам ваш проект без докера, нужны ли вашему проекту какие-то дополнительные параметры запуска и т.д. Мое мнение: доп. сервисов вполне достаточно, т.к. настройка еще и вашего проекта в дополнение ко всему этому делу может быть мучительным занятием. В крайнем случае добавьте описание/команду как запустить ваш проект с уже запущенными в докере доп. сервисами.

   Ну и в самом проекте я бы рекомендовал в качестве дефолтных параметров запуска использовать параметры, которые завязаны на ваши сервисы (например, в java, в yaml файле в качестве дефолтных адресов указать адреса, указанные в compose файлике, тогда просматривающему ваш проект достаточно будет запустить лишь compose и проект, без доп. настройки env переменных, например). Ну и рекомендую все это также вынести в отдельную папку docker для поддержания структуры.

Итого: У вас может получиться что-то похожее на этот readme, содержащее достаточно информации для всех интересующихся, при этом не перегруженное и не длинное. Надеюсь эта статья будет кому-то полезна, конечно, это не гарантирует, что правильно оформя ваши проекты вы сразу найдете работу/пользователей (not in this economy), но это однозначно увеличит ваши шансы.

6. Honorable mention:
   Можете указать дефолтные адреса, что, где и как доступно и другую необходимую доп. информацию, как это сделал я, но это уже зависит от типа вашего проекта, разумеется.

P.S: Язык оформления, разумеется, выбирайте сами, в зависимости от того, какая "целевая аудитория". Для себя я пришел к выводу, что русскоязычные разработчики поймут англоязычное описание, но англоязычные не поймут русскоязычное