Как написать README на GitHub

Добавить базовое описание репозитория продукта на GitHub.

Файл README.md в корневой папке репозитория — особенный файл для любого продукта. В нём, как правило, даны самые основные сведения о репозитории:

• название продукта;
• краткое описание;
• основные возможности;
• инструкция по установке и/или подключению;
• инструкция по запуску в режиме разработчика и в режиме пользователя;
• список участников репозитория, которые разрабатывают и поддерживают продукт.

Написать хорошее описание продукта непросто, и это требует определённого навыка. Хорошей идеей будет посмотреть, как это делают коллеги. В каждом продукте есть и что-то схожее с остальными, и по-своему уникальное. Важно правильно расставить акценты. Помните, что README.md — обложка вашего проекта.

Потребителями README.md, скорее всего, будут разработчики и продвинутые пользователи, например, администраторы систем. Язык программирования, выбранные задачи репозитория, принятые в сообществе нормы описания будут определять содержимое файла. Хорошее описание поможет продвинуть продукт. Его легче будет найти на GitHub и в поиске, а ещё им будет комфортнее пользоваться. Хорошее описание привлекает хороших разработчиков.

В README.md, в первую очередь, ответьте на следующие вопросы:

1. Почему был создан продукт? В ответе на этот вопрос можно опираться на такие понятия как мотивация, история, потребности, мечты и прочее.
2. Для чего был создан продукт? Здесь лучше всего описать те проблемы и потребности, которые закрывает продукт.
3. Чем продукт лучше аналогов? Если у продукта есть аналоги, необходимо написать об отличиях и особенностях продукта.
4. Как установить продукт? Тут необходимо написать краткую инструкцию по установке.
5. Как пользоваться продуктом? Тут нужно написать краткую инструкцию пользователя из серии «Быстрый запуск».
6. Как помочь продукту развиваться? Здесь лучше ответить тем разработчикам, которые хотят поучаствовать в развитии продукта.
7. Кто разрабатывает продукт? Самый простой ответ на этот вопрос — список разработчиков, но может быть и описание компании или инициативы, в рамках которой продукт был создан или развивается.

В README.md используется разметка в формате Markdown. Структурируйте текст файла, выделяя каждый блок заголовками и подзаголовками. В интерфейсе GitHub заголовки хорошо выделяются на фоне текста до третьего уровня, поэтому старайтесь использовать заголовки первого и второго уровня. Возможная структура README.md:

• название (заголовок первого уровня) — название продукта без указания версии, если в этом нет особенной необходимости, например, из-за лицензии;
• описание (заголовок второго уровня) — краткое описание продукта, в котором можно ответить на вопросы 1, 2 и 3 из списка вопросов выше;
• установка (заголовок второго уровня) — описание процесса установки продукта (вопрос 4);
• использование (заголовок второго уровня) — описание процесса использования продукта (вопрос 5);
• разработка (заголовок второго уровня) — описание процесса того, как принять участие в разработке проекта или запрет на это (вопрос 6);
• участники (заголовок второго уровня) — перечисление всех, кто принимал или принимает участие в разработке продукта (вопрос 7).