Как писать README.md?

1. Почему это важно?

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

2. Что писать в README?

В идеальном случае,  README вашего проекта должен отвечать на вопросы “что”, “зачем” и “как”. Но вот вам ещё список толковых вопросов:
– О чём проект?
– Почему вы разработали его, какова была ваша мотивация?
– Какую проблему он решает? Кому он нужен?
– Чему вы научились (если это тестовый проект)?
– Что делает ваш проект уникальным? Отличным от форков (если они есть)

3. Типичная структура

Description/Introduction/About (Описание/Введение)
Часто, этот блок вообще не называют. Его главная цель – описание проекта, чтобы человек, просматривающий твой проект, мог понять суть проекта уже в первые секунды прочтения информации о проекте.

Stack/Dependencies (Технологии/Зависимости)
Технологии или зависимости проекта, включающий языки программирования, библиотеки и фреймворки, используемые в твоём проекте (например: Python, React, …). Если у тебя есть веб-приложение, использующее внешний общедоступный API, обязательно укажи это.

Design (UI)
Примеры пользовательского интерфейса, связанные с проектом. Если у проекта есть пользовательский интерфейс, ты можешь вставить GIF-файл, видео или изображение пользовательского интерфейса.

Или, если это приложение, работающее в терминале, ты можешь создать GIF, который показывает, как с ним работать. Это хороший способ передать представление о том, как взаимодействовать с приложением и что увидит пользователь при запуске проект.

Features (Функции/Методы)
Если твой проект имеет методов работы с ним, лучше добавить раздел “Методы” и перечислить их здесь.

Quick Start/Running/Installation (Как запустить или установить проект)
Чуть ли не самый важный пункт. Инструкция по установке, запуску и использованию проекта. Это полезно, если кто-то хочет запустить проект с нуля, они должны найти всю необходимую информацию в README проекта, не требуя помощи от тебя. Если инструкции простые, их можно включить в файл README. Ты также можешь сослаться на другой файл в проекте, если инструкции длинные.