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

Файл README может рассказать очень много о вашем проекте. Как быть уверенным, что файл хорош:

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

Кто читает README?

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

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

Что это за проект?

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

К сожалению, я нашел только 1 из 10 недавно обновленных игр с описанием, что это за игра.

Что проект делает?

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

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

Я недавно сменил работы и получил новый, чистый ноутбук. Несмотря на то, что с моей последней статьи прошло всего несколько недель, я не смог вспомнить, как я собрал этот сайт и как собрать его на новой машине.

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

Параметры проекта

По мере того как проект будет расти, в нем будут участвовать все больше людей, будет появляться все больше параметров, которые можно изменить. Как изменить глобальные переменные? Как включить режим отладки? Что можно менять в файле конфигов? Все эти пункты нужно отразить в файле README, для того чтобы пользователи могли получить доступ ко всем возможностям.

Сборка и деплой

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

Посмотрите даже на этот блог: Я могу работать над определенной идей какое-то время, а потом отложить блог на недели. Но даже после работы с различными проектами, языками и CMS, я всегда могу узнать, как правильно развернуть каждый из проектов.

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

Контрибьютинг

Каждый проект имет свои собственные практики и стандарты, основанные коммандой, которая разрабатывает его.

README должен включать небольшой введение для тех кто хочет присоединиться к проекты, например:

• Какой стандарт кодирования принят в проекте?
• Как оформлять комиты и ветки?
• Как можно обсудить что-либо с командой разработки?

Это может новым участникам быстрее присоединиться к проекту.

Лицензия

Есть много статей про лицензии в проектах с открытым исходным кодом. Но в файле README обязательно должны быть отражены следующие пункты:

• Можно ли использовать, модифицировать и дописывать проект?
• Можно ли использовать код проекта в других проектах (например на работе)?

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

Что дальше?

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

Я решил сделать шаблон для README, который можно просто копировать во все проекты. Со временем шаблон стал неотъемлемой частью всех моих проектов. Вы можете найти проект с шаблоном на гитхабе или просто скопировать шаблон к себе в проект:

$ curl https://raw.githubusercontent.com/jehna/readme-best-practices/master/README-default.md > README.md

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

Я буду счастлив увидить, как шаблон становится еще полнее. Поэтому если вам кажется, что что-то пропущено, то откройте пулл-реквест, чтобы улучшить шаблон.

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