Перевод статьи «How to write a kickass README».
Вероятно, README это самая простая часть документации любого проекта с открытым исходным кодом. Хороший README сообщает людям не только о том, что делает проект и для кого он предназначен, но и о том, как именно нужно использовать проект и как принять участие в его разработке.
Если не уделить должного внимания составлению хорошего README, где объяснялось бы, как пользоваться проектом и для чего он вообще создан, такой проект не оправдает себя в качестве именно open source проекта, поскольку другие разработчики с меньшей вероятностью станут в нем участвовать.
Что такое README?
По сути, README это просто текстовый файл (в формате .txt или .md), играющий роль быстрой справки по проекту или директории. Обычно это самая заметная часть документации и landing page для большинства проектов с открытым кодом. Даже само название файла пишется одними заглавными буквами, чтобы привлечь внимание читателя и побудить его прочесть это файл в первую очередь.
Доказано, что файлы README появились уже в 1970-е. Самый старый найденный мной экземпляр README датируется 27 ноября 1974 года (создан для DEC компьютера PDP-10). Есть много версий, почему файл первичной документации принято называть именно README, но основных среди них две:
- Программисты мэйнфреймвов, работавшие с перфокартами, оставляли стопку инструкций (в бумажном виде) на передней панели и помечали их надписью «READ ME!» («Прочти меня!»).
- Название является отсылкой к «Алисе в стране чудес» Льюиса Кэрролла. Там Алиса находит пузырек с надписью «DRINK ME» («Выпей меня») и пирожное с надписью «EAT ME» («Съешь меня»). И то, и другое, позволяет ей меняться в размерах.
Что нужно включить в файл README?
Так что же должен содержать идеальный файл README? В качестве отправной точки я рекомендую воспользоваться следующим списком:
1. Название продукта
Не забудьте дать своему проекту имя. На GitHub просто на удивление много безымянных проектов.
2. Введение или краткое описание
Напишите две-три короткие строчки, поясняющие, что делает ваш проект и для кого он предназначен. Не вставляйте заголовки типа «Вступление», «Обзор» и т. п. — и так очевидно, что это введение.
3. Необходимые условия для использования продукта
Сразу после введения добавьте раздел, где будут перечислены все знания и инструменты, необходимые тому, кто пожелает воспользоваться вашим проектом. Например, если продукт запускается на последней версии Python, напишите, что нужно установить Python.
4. Как установить программу
Опишите шаги инсталляции! Просто поразительно, сколько есть проектов, где описано, как использовать продукт, но нет ни слова о том, как его установить. Вероятно, ожидается, что читатель волшебным образом сам догадается. Если процесс установки достаточно длинный (сложный), обязательно разбейте его на отдельные этапы и пронумеруйте их.
5. Порядок использования
Опишите, как пользователь может использовать ваш проект после установки. Обязательно включите примеры использования, ссылки на пояснение опций команд или флагов (если считаете, что это будет полезно). Если у вас есть более подробная документация в отдельном файле или на сайте, поставьте ссылку на нее.
6. Как принять участие в проекте
Опишите шаги, которые должен пройти потенциальный контрибьютор. Возможно, вы могли бы создать руководство в отдельном файле и поместить ссылку на него в README. Укажите в руководстве все, что вы хотите, чтобы люди знали, прежде чем отправлять пул-реквесты.
7. Добавьте список контрибьюторов
Укажите всех людей, которые участвовали в создании этого проекта. Это хороший способ сделать так, чтобы open source казался плодом командных усилий. Также таким образом вы поблагодарите всех людей, потративших время на участие в вашем проекте.
8. Добавьте раздел с благодарностями
Также, если вы использовали чью-то еще работу (код, дизайн, изображения и т. п.) и копирайт обязывает вас указать автора, вы можете сделать это , добавив специальный раздел. Тут можно поблагодарить и других разработчиков или даже целые организации, оказавшие помощь проекту.
9. Контактная информация
Возможно, вы замкнутый человек, избегающий любой публичности, и совершенно не хотите рассекречивать свои контакты. Но лучше все же их добавить где-нибудь на видном месте — на случай, если у людей возникнут вопросы по продукту, если кто-то захочет принять участие в разработке или — чем черт не шутит! — если кто-то так восхитится вашим проектом, что захочет предложить вам работу.
10. Информация о лицензии
Информацию о лицензии продукта определенно стоит включить в файл README. Стартапы и прочие компании, использующие стороннее ПО, не смогут использовать ваш продукт, если не будут знать, на каких условиях могут это делать. Посмотреть список видов лицензий можно на choosealicense.com или opensource.org.
Добавьте немного блеска
Если хотите, чтобы ваш README выделялся и имел привлекательный вид —
- Добавьте логотип. Если у вашего проекта есть лого, разместите его в верхней части README. Благодаря брендингу проект выглядит более профессиональным, кроме того, это помогает людям его запомнить.
- Добавьте значки или плашки. Они помогут вам быстро показать посетителям текущий статус проекта, лицензию, обновление зависимостей. Плюс, они просто круто выглядят! Можно воспользоваться готовыми значками или создать собственные на Shields.io.
- Добавьте скриншоты. Иногда простой скриншот или серия скриншотов бывают полезнее тысячи слов. Но будьте внимательны! Если вы используете скриншоты, следите за их актуальностью и обновляйте по мере обновления проекта.
- Используйте эмодзи(?). Сегодня во многих проектах используются эмодзи, но, конечно, только от вас зависит, хотите ли вы тоже их использовать. Это может быть хорошим способом добавить немного цвета и юмора в ваш README и слегка «очеловечить» проект.
Ресурсы
Если хотите узнать еще что-то о написании README, я советую воспользоваться следующими источниками:
- Выступление Дэниела Бека «Write the Readable».
- Выступление Лорны Джейн Митчелл «Github as a landing page».
- README generator Франгка Абгралла.
[customscript]techrocks_custom_after_post_html[/customscript]
[customscript]techrocks_custom_script[/customscript]