Когда я только познакомился с GitHub, я даже не представлял, что это такое README-файл и какую функцию он выполняет. Между нами говоря, я создал учетную запись на GitHub только потому, что мне сказали, что у каждого уважающего себя разработчика должна быть такая учетная запись, где он может размещать свой код.
Так как я был новичком, моя учетная запись довольно долго простаивала. Но позже, в силу своей увлеченности технологиями, я начал наблюдать за другими разработчиками и просматривать их работы на GitHub. И я заметил кое-что общее: у всех у них были крутые проекты, и все они вносили свой вклад в разработку открытого исходного кода, но у всех их проектов были подробно описанные README-файлы.
И вот здесь мой интерес к README-файлам вырос, и я решил попробовать добавить такой файл в свой проект. Не стану врать, я сделал это кое-как, не понимая, как это нужно было сделать на самом деле. И, если честно, то получилось не очень. Вы можете посмотреть это ЗДЕСЬ.
Какое-то время все так и было. Но, обучившись и набравшись опыта, я смог научиться писать более качественную документацию, например, вот ТАКУЮ, которая упрощает работу с проектом и помогает другим разработчикам также принимать в этом участие.
Кроме того, стоит отметить, что хороший README-файл может помочь вам выделиться среди толпы разработчиков, размещающих свои работы на GitHub.
В этой статье мы разберем, что же такое README-файл и как его писать. Но для начала давайте разберемся, что мы имеем в виду под понятием «README-файл».
Что такое README-файл?
Если выражаться простыми словами, то README-файл – это руководство, в котором содержится подробное описание проекта, над которым вы работаете.
Также его можно определить, как документацию с рекомендациями по использованию проекта. Как правило, он содержит инструкции по установке и запуску проекта.
Вам, как разработчику, следует знать, как правильно документировать свой проект посредством README-файла, так как:
- Это первый файл, который увидит человек, желающий ознакомиться с вашим проектом, поэтому этот файл должен быть довольно краткий, но при этом подробный.
- Это выделит ваш проект среди множества других проектов. При этом, разумеется, ваш проект должен быть хорош сам по себе.
- Это поможет вам направить свое внимание на то, каким требованиям должен удовлетворять ваш проект и как он будет это делать.
- Это поможет развить ваши навыки письма. Как сказал Фридрих Ницше:
«Хороший писатель имеет не только свой собственный ум, но и ум своих друзей.»
Когда вы работаете над проектом, помните о том, что вам может потребоваться помощь других разработчиков. Именно поэтому важно сопровождать его дополнительным руководством.
Например, у моего первого проекта, который я опубликовал ранее, нет хорошего README-файла. И несмотря на тот факт, что сам по себе проект был потрясающим, новичку было бы сложно понять, что именно ему стоит ожидать, когда он клонирует мой репозиторий. Кто знает, может это закодированный вирус.
Каким бы замечательным ни был бы ваш проект, другие разработчики не захотят с ним работать и пытаться разбирать, что в нем происходит, если у него не будет хорошего README-файла.
А теперь взгляните на этот проект. Здесь вы уже можете разобрать, что делает проект, как он работает и с чего вам стоит начать, если вы хотите воспользоваться им в своих целях или хотите внеси свой вклад в этот проект.
Видите, насколько мощным инструментом может быть хорошо написанный README-файл и как он может изменить ваш проект.
Так что, давайте разберем, как написать такой файл для вашего проекта.
Как написать хороший README-файл – пошаговое руководство
Отмечу, что нет какого-то единого правильного способа написания хорошего README-файла. Но есть один неправильный – вообще не писать README-файл.
Изучив несколько различных README-файлов, я, само собой, нашел несколько оптимальных вариантов. И я поделюсь ими с вами. Как я обычно говорю сам себе:
«Каждый день – это шанс научиться чему-то новому.»
Так что, по мере того как вы будете продвигаться по карьерной лестнице, у вас появятся свои собственные идеи, как можно написать хороший README-файл и как его улучшить. Не исключено, что вы разработаете свое собственное уникальное руководство.
Прежде чем мы приступим, стоит отметить, что, когда вы пишете README-файл для своего проекта, он должен содержать в себе ответы на вопросы, касающиеся проекта: что он делает, для чего и как.
Вот несколько вспомогательный вопросов, которые могут вам помочь:
- В чем заключается цель создания проекта?
- Для чего вы создали этот проект?
- Какую проблему решает этот проект?
- Что вы изучили, разрабатывая проект?
- Чем ваш проект отличается от других?
Если в вашем проекте много функций, то вы можете добавить раздел «Функции» и перечислить их в нем.
Что добавить в README-файл
1. Наименование проекта
Это название проекта, которое описывает его буквально одним предложением. С его помощью люди могут понять, в чем заключается основная задача проекта.
2. Описание проекта
Это важный компонент вашего проекта, но многие разработчики-новички почему-то пренебрегают им.
Описание вашего проекта – это очень важный аспект. Описание, сделанное на совесть, позволит вам показать свою работу другим разработчикам (а также потенциальным работодателям) в выгодном свете.
То, насколько качественно составлено описание, позволяет отделить хорошие проекты от плохих. В случае хороших проектов, это шанс описать и продемонстрировать:
- Какую задачу выполняет ваше приложение
- Почему вы использовали те, а не иные технологии
- Некоторые проблемы, с которыми вы столкнулись, и функции, которые вы хотите реализовать в будущем.
3. Оглавление (не обязательно)
Если ваш README-файл получился очень большим, то вы можете добавить оглавление, чтобы пользователи могли легко перемещаться между разделами. Читатели смогут с легкостью перемещаться по проекту.
4. Как установить и запустить проект
Если вы работаете над проектом, который пользователь должен устанавливать и запускать локально на своем компьютере, например, POS, то вы должны добавить в файл пошаговую инструкцию, как установить проект. Кроме того, вы должны указать все необходимые зависимости, если они есть.
Подготовьте пошаговое описание того, как нужно настраивать и запускать среду разработки.
5. Как использовать проект
Подготовьте инструкции и примеры, которые помогут пользователям/соавторам правильно использовать проект. Если у них вдруг возникнет проблема, это облегчит им жизнь – у них всегда будет куда можно обратиться за помощью.
Помимо этого, вы можете использовать наглядные пособия, например, скриншоты, с помощью которых можно показать примеры запущенного проекта, а также структуру и принципы проектирования, которые вы использовали при разработке вашего проекта.
Кроме того, если ваш проект будет требовать этапа аутентификации, то есть имя пользователя и пароль, здесь вы можете добавить необходимые ученые данные.
6. Сведения об авторах
Если вы работали над проектом как команда или как часть организации, то перечислите своих соавторов/членов команды. Также вы должны указать ссылки на их профили GitHub и социальные сети.
Помимо этого, если вы использовали какие-то руководства или ссылались на какой-то определенный материал, который может помочь пользователю в создании этого самого проекта, добавьте на них ссылки здесь же.
Это лишь способ выразить свою благодарность, а также помочь другим получить копию проекта из первых рук.
7. Лицензия
Для большей части README-файлов это последний раздел. Отсюда разработчики могут узнать, что они могут делать с вашим проектом, а что не могут.
Существует разные типы лицензий. Все зависит от типа проекта, над которым вы работаете. Исходя из того, какую лицензию вы выберите, пользователи смогут вносить в проект тот или иной вклад.
Самая распространенная лицензия – GPL (General Public License – общедоступная лицензия). Она позволяет другим пользователям вносить изменения в ваш код и использовать его в коммерческих целях.
Пока мы пробежались по самым минимальным требованиям для хорошего README-файла. Но вы можете рассмотреть возможность добавления и других разделов, которые сделают ваш проект еще более эффектным и интерактивным.
Дополнительные разделы README-файла
8. Значки (плашки)
Значки не являются обязательным компонентом, но с их помощью вы можете продемонстрировать другим разработчикам, что вы понимаете, что вы делаете.
С помощью этого раздела вы можете добавить ссылки на важные инструменты, а также можете продемонстрировать некоторые статические данные о вашем проекте, например, количество ответвлений, соавторов, неразрешенных проблем и т.д.
Ниже я прикрепил скриншот одного из моих проектов. На нем я продемонстрировал то, как можно использовать значки:
Прелесть этого раздела в том, что он обновляется автоматически.
Не знаете, где их взять? Ознакомьтесь со значками, размещенными на shields.io. Там есть огромное количество различных значков, которые помогут вам. Да, сейчас вы можете не понимать, что это такое, но со временем вы поймете.
9. Как можно внести свой вклад в проект
В особенности этот раздел будет полезен, если вы работаете над проектом с открытым исходным кодом, для разработки которого вам может потребоваться помощь других разработчиков. Вы можете добавить некоторые рекомендации, чтобы проинформировать их о том, как они могут внести свой вклад в проект.
Обязательно проследите за тем, что вы выбрали правильную лицензию для проектов с открытым исходным кодом. Это необходимо для того, чтобы в будущем избежать конфликтов. А добавление рекомендаций по вкладу в проект сыграет в этом немаловажную роль.
Некоторые самые обычные руководства включают Соглашение для участников и Руководство по сотрудничеству. Эти документы помогут вам при установлении правил, касающихся вашего проекта.
10. Тесты
Приложите дополнительные усилия, напишите тесты для вашего приложения и приложите примеры кода и способы, как их запустить.
Таким образом, вы сможете продемонстрировать, что вы уверены в том, что ваш проект будет работать без каких-либо проблем. Это позволит другим людям также поверить в успех этого проекта.
Дополнительные моменты
Есть несколько дополнительных моментов, на которые стоит обратить внимание, когда вы пишете README-файл:
- Поддерживайте его в актуальном состоянии. Рекомендуется следить за тем, чтобы ваш файл всегда был актуальным. Если появляются какие-то изменения, обязательно обновить файл где это необходимо.
- Выберите язык. Все мы из разных стран и, соответственно, говорим на разных языках. Но это совсем не значит, что вам нужно переводить ваш код на какой-либо другой язык. Будет хорошо, если вы напишете README-файл на английском языке, так как он считается общепризнанным международным языком. Если ваша целевая аудитория не знает английский язык, вы можете воспользоваться переводчиком.
Заключение
Вот и все! Вы узнали все, что нужно для того, чтобы улучшить качество ваших README-файлов или даже написать свой первый README-файл.
На данном этапе я уверен в том, что вы способны добавить интерактивное и информативное руководство к вашему следующему проекту или к уже существующему и выделить его среди других проектов.
Существует огромное количество инструментов, которые можно использовать для автоматического создания README-файлов. Однако будет лучше, если вы попробуете научиться писать их самостоятельно, прежде чем перейдете к их автоматическому созданию.
