Как написать хороший README для вашего проекта на GitHub

Статья написана студентом Хекслета. Мнение автора может не совпадать с позицией редакции

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

Когда я впервые зашла на Github, честно говоря, я понятия не имела, что такое файл README (хотя я видела его в проектах других людей).

Во-первых, зачем мне хороший файл README?

Файл README — это руководство, которое дает пользователям подробное описание проекта, который вы разместили в своем репозитории.

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

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

README должен ответить на следующие вопросы: что, почему и как:

Что было вашей мотивацией?
Какую проблему это решает?
Что вы узнали?
Что отличает ваш проект от других?

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

Как написать хороший файл README

Вот шаги, которые вы должны предпринять, чтобы написать README.

Включите название вашего проекта

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

Напишите описание

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

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

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

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

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

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