Заметки о README на GitHub

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

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

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

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

Что должно быть включено в файл README

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

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

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

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

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

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

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

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

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

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

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

Кредиты

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

Лицензия

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

Также…

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

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

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

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

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

Ссылки

  1. https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes
  2. https://www.makeareadme.com/
  3. https://github.com/18F/open-source-guide/blob/18f-pages/pages/making-readmes-readable.md
  4. https://www.freecodecamp.org/news/how-to-write-a-good-readme-file/

Оцените статью
devanswers.ru
Добавить комментарий