Как написать хороший README: краткий курс

После Hacktoberfest в проектах с открытым исходным кодом появилось много новых правок. Только за октябрь было сделало более 400 000 запросов на включение кода. Это невероятно!

Я решил подробнее изучить проекты с большим количеством правок. У этих проектов есть кое-что общее: отличный readme.md-файл. Сомневаюсь, что можно внести так много правок без хорошего readme. Между качеством readme и количеством правок определенно есть связь!

Обратим внимание на несколько известных проектов: React, Vue, freeCodeCamp, Sourcerer и Serverless. В каждом из этих проектов readme.md-файл идеально сочетает в себе документацию, общие сведения о проекте, часто задаваемые вопросы и инструкцию по внесению правок. В них наглядно показано, что это за проект, какая у него экосистема, какое вокруг него сложилось сообщество.

Любому сообществу вокруг open source проекта нужен файл, который упростил бы коммуникацию. Этот файл похож на руководство, в нем разработчики детально рассказывают о проекте. Тем не менее, что же такое файл readme.md?

Что такое readme?

Файл readme.md — это основа любого проекта с открытым исходным кодом. Он дает полное понимание того, куда движется проект. Он объясняет, что это за ПО и зачем оно нужно. В нем указаны предварительные условия, которые помогают новым участникам проекта быстрее включиться в работу.

Самое важное: в readme-файле сказано, как запустить это ПО с целью разработки. Также в readme обязательно должна быть инструкция по развертыванию ПО в среде эксплуатации.

Зачем нужен readme?

Мы составляем резюме, развиваем свой профиль на GitHub, заводим личный сайт, чтобы люди обратили внимание на нашу работу. Такой же подход применим и к проектам с открытым исходным кодом. Readme.md — это резюме вашего ПО. Добавьте в него все, что поможет будущим участникам проекта лучше понять ваше ПО.

Самый разумный подход: сначала написать readme.md, а уже затем опубликовать проект. Так будет намного проще отвечать на вопросы и помогать новым участникам.

Заведите себе правило: любой проект должен начинаться с readme-файла. Обязательно добавьте его в корневой каталог вашего проекта, чтобы его было видно на GitHub.

Как написать readme?

К счастью, изобретать велосипед не придется. Существует несколько отличных шаблонов. Помните, что у readme.md должна быть логичная структура: этот файл должен быть простым и понятным, чтобы сразу после его прочтения можно было приступить к работе.

Взгляните на этот прекрасный шаблон от Билли Томпсона. Он поможет написать отличный readme в считанные минуты.

---

Название проекта

Один параграф, описывающий проект

Приступая к работе

Инструкция о том, как получить копию этого ПО и запустить его на локальном компьютере с целью разработки и тестирования. Подробную информацию о развертывании ПО в условиях эксплуатации см. в разделе «Развертывание».

Предварительные условия

Что нужно для установки ПО, инструкции по установке дополнительных компонентов.

Give examples

Установка

until finished

End with an example of getting some data out of the system or using it for a little demo

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

Примеры

В конце на примере объясните, как извлечь данные из системы.

Тестирование

Объясните как запустить автоматическое тестирование этой системы.

Сквозное тестирование

Объясните, что проверяют эти тесты и зачем они нужны.

Пример

Тестирование стандартов оформления кода

Объясните, что проверяют эти тесты и зачем они нужны.

Пример

Развертывание

Более подробно расскажите, как развертывать ПО в условиях эксплуатации

Создано с помощью

• Dropwizard — Платформа для разработки приложений
• Maven — Управление зависимостями
• ROME —Генерация RSS-лент

Внесение правок

Прочтите CONTRIBUTING.md, чтобы получить подробную информацию о правилах и процессе подачи запросов на включение кода.

Управление версиями

Для управления версиями мы используем SemVer. Информацию о доступных версиях см. в тегах в этом репозитории.

Авторы

• Билли Томпсон — Начальный этап работы — PurpleBooth

См. список тех, кто вносил правки в проект.

Лицензия

Этот проект лицензируется в соответствии с лицензией MIT — подробности см. в файле LICENSE.md.

Благодарности

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

---

Есть несколько моментов, которые нужно упомянуть. Прежде всего, этому шаблону не хватает взаимодействия с сообществом. Не стесняйтесь добавлять изображения, значки, изображения, видео и даже GIF в ваши readme.md-файлы. Не забывайте, что ваша цель — сделать так, чтобы ваш проект понравился людям. Отдельную благодарность нужно выразить тем, кто помогал и вносил правки.

Помните, что вам нужно привлечь внимание сообщества и поблагодарить тех, кто вносит правки. Используете значки, чтобы показать статус сборки, полноту тестирования, PR-статус, наличие уязвимостей, лицензию. Экспериментируйте с ними, так ваш проект будет выглядеть серьезнее. Одобрение других людей — это самый важный показатель в сообществе разработчиков ПО с открытым исходным кодом. Скопируйте приведенные ниже значки или сделайте их сами. ?

Еще один потрясающий инструмент, с помощью которого можно добавить наглядности и поблагодарить тех, кто вносит правки — это Hall of Fame.

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

 

О чем я забыл упомянуть?

Если ваш проект начнет стремительно расти, стоит задуматься о создании Contributing.md, в котором вы расскажете о том, как подавать запросы на включение кода. Этот файл станет официальным руководством для тех, кто захочет внести вклад в ваш проект.

Не останавливайтесь на достигнутом. Во-первых, добавьте license.md, чтобы подробнее рассказать, насколько открыт ваш код. Затем напишите code_of_conduct.md, чтобы объяснить общие правила работы для разработчиков: этот «свод правил поведения» необходим для комфортной работы друг с другом.

Заключение

У всех успешных проектов с открытым исходным кодом readme.md сделан очень качественно, и это не случайность. Внимание людей ограничено. Хороший readme.md помогает привлечь разработчиков, которые будут вносить вклад в проект. Глядя на freeCodeCamp и Sourcerer, можно увидеть много общего: в их readme просто и наглядно рассказывает о функциях, содержимом и документации, дает рекомендации тем, кто хочет внести вклад в проект.

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

Перевод статьи Adnan Rahić: A crash course on writing a better README