В первый раз, когда я увидел слово «README», я пытался выполнить задание. Инструкция заключалась в том, чтобы создать файл README.md; добавьте некоторую информацию о проекте и отправьте ее на мой GitHub. Я не совсем понимал его назначение, пока мне не пришлось работать над совместным проектом, требующим развертывания.

Передовая практика кодирования требует, чтобы в каждом репозитории был файл README.


Что такое файл README?

Файл README — это текстовый файл, который предоставляет пользователям основную необходимую информацию о вашем проекте. В нем описывается ваш проект, указывается, почему ваш проект ценен, что пользователи могут делать с вашим проектом и как они могут его использовать, среди прочего. Обычно это первое, с чем люди сталкиваются, когда проверяют любой проект, который есть в вашем репозитории. Это должно быть кратким.


Что включить в файл README


Описание Проекта:

Правильно составленное описание включает в себя следующее:
а. Название вашего проекта;
б. Чем занимается ваш проект;
в. кто целевой пользователь;
д. Как это работает; а также
е. Технологии, которые вы использовали, и почему вы их использовали

Описание проекта позволяет другим разработчикам и соавторам получить общее представление о том, что влечет за собой ваш проект.


Как установить проект

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


Как использовать проект

Не забудьте направлять пользователей о том, как использовать проект. Предоставьте пошаговые инструкции. Эти инструкции будут ориентиром, когда пользователи столкнутся с какими-либо трудностями.

базовое использование на github readme

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

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


Как внести свой вклад в проект

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


Кредиты

Вы должны включить список людей, с которыми вы работали над проектом, если вы работали над проектом в команде. Вы можете добавить их профили GitHub.


Лицензия

Существуют различные типы лицензий. Тот, который вы можете выбрать, зависит от типа проекта, который вы создаете. Лицензия помогает сотрудникам узнать, что можно делать, а чего нельзя.

Лицензия GitHub


Также…

  • Если ваш README очень длинный, вы можете добавить оглавление, чтобы пользователям было легко переходить к различным разделам. Читателям будет легче перемещаться по проекту.

  • Поддерживайте его в актуальном состоянии. Хорошей практикой является обеспечение актуальности вашего файла. Обязательно обновите его при необходимости.

  • Будьте лаконичны и указывайте только необходимые детали. Ваша документация должна содержать всю остальную информацию.

  • Существуют инструменты, которые вы можете использовать для автоматического создания файла README для вашего проекта.

Наслаждайтесь 🖤


использованная литература