Файл Readme, что это такое

Обновлено: 06.07.2024

Файл README — это важное руководство, которое дает другим разработчикам подробное описание вашего проекта GitHub.

Хороший файл README помогает вашему проекту выделиться среди других проектов и должен быть не хуже самого проекта.
Это первое, на что следует обратить внимание при знакомстве с вашим проектом, поэтому оно должно быть довольно кратким, но подробным.
Качество описания README отличает хороший проект от плохого.
Во многих случаях README.md размещается как веб-сайт; убедитесь, что ваша веб-страница выглядит так же круто, как и ваш проект!

Содержание файла Readme:

Укажите название вашего проекта. Это название проекта. Он описывает весь проект в нескольких словах и помогает людям понять основную цель и задачу.
Напишите описание. Ваше описание является неотъемлемой частью вашего проекта. Правильно составленное описание позволит вам продемонстрировать свою работу другим разработчикам, а также потенциальным работодателям.
Как использовать ваш проект: предоставьте инструкции и примеры, чтобы пользователи или участники могли использовать проект. Это облегчит им задачу, и если они столкнутся с проблемой, у них всегда будет источник информации.
Включите кредиты. Если вы работали над проектом в команде, перечислите членов вашей команды. Вы также должны включить их профили GitHub.

Вы также можете добавить следующие сведения в файл Readme:

Какова была ваша мотивация? Почему вы создали этот проект?
Какую проблему решает проект? Или что он делает?
Почему вы использовали определенные технологии? Если в вашем проекте много функций, перечислите их здесь.
Упомяните некоторые проблемы, с которыми вы столкнулись, и функции, которые вы надеетесь реализовать в будущем.
Упомяните все, чем, по вашему мнению, вы гордитесь в этом проекте.
Чему вы научились в процессе?
Что дальше с проектом?
Упомяните языки, фреймворки, базы данных и т. д.
Предоставьте ссылки для развертывания или любые другие необходимые ссылки.

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

README – это текстовый файл, который знакомит с проектом и объясняет его. Он содержит информацию, которая обычно требуется для понимания сути проекта.

Зачем мне это делать?

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

Кто должен это сделать?

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

Когда я должен это сделать?

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

Куда его поместить?

В каталоге верхнего уровня проекта. Это где кто-то, кто новичок в вашем проекте начнет. Службы размещения кода, такие как GitHub, Bitbucket и GitLab, также будут искать ваш файл README и отображать его вместе со списком файлов и каталогов в вашем проекте.

Как мне это сделать?

Несмотря на то, что файлы README могут быть записаны в любом текстовом формате, наиболее распространенным в настоящее время является формат Markdown. Это позволяет вам добавить легкое форматирование. Вы можете узнать больше об этом на веб-сайте CommonMark, где также есть полезное справочное руководство и интерактивный учебник.

Некоторые другие форматы, которые вы можете встретить, – это обычный текст, reStructuredText (распространенный в проектах Python) и Textile.

Вы можете использовать любой текстовый редактор. Существуют плагины для многих редакторов (например, Atom, Emacs, Sublime Text, Vim и Visual Studio Code), которые позволяют вам предварительно просматривать Markdown во время редактирования.

Вы также можете использовать специальный редактор Markdown, например Typora, или онлайн-редактор, например StackEdit или Dillinger. Вы даже можете использовать редактируемый шаблон ниже.

Шаблон

Ввод уценки (редактируемый)

Foobar — это библиотека Python для работы со множественным числом слов.

Установка

Используйте pip менеджера пакетов для установки foobar.

Использование

Содействие

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

Не забудьте обновить тесты соответствующим образом.

Лицензия

Предложения по хорошему файлу README

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

Выберите понятное название для вашего проекта.

Описание

Сообщите людям, что конкретно может сделать ваш проект. Предоставьте контекст и добавьте ссылку на любую ссылку, с которой посетители могут быть незнакомы. Здесь также можно добавить список функций или подраздел «Фон». Если у вашего проекта есть альтернативы, это хорошее место, чтобы перечислить отличительные факторы.

Значки

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

Визуальные эффекты

В зависимости от того, что вы делаете, может быть хорошей идеей включить скриншоты или даже видео (часто вы будете видеть GIF-файлы, а не реальные видео). Такие инструменты, как ttygif, могут помочь, но попробуйте Asciinema для более сложного метода.

Установка

В рамках определенной экосистемы может существовать общий способ установки, например с помощью Yarn, NuGet или Homebrew. Однако рассмотрите возможность того, что тот, кто читает ваш README, является новичком и хотел бы получить дополнительные указания. Перечисление конкретных шагов помогает устранить двусмысленность и побуждает людей использовать ваш проект как можно быстрее. Если он работает только в определенном контексте, таком как конкретная версия языка программирования или операционная система, или имеет зависимости, которые необходимо установить вручную, также добавьте подраздел «Требования».

Использование

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

Поддержка

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

Дорожная карта

Если у вас есть идеи для выпусков в будущем, рекомендуется перечислить их в файле README.

Содействие

Укажите, открыты ли вы для пожертвований и каковы ваши требования для их принятия.

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

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

Авторы и благодарность

Выразите признательность тем, кто внес свой вклад в проект.

Лицензия

Для проектов с открытым исходным кодом укажите, как они лицензируются.

Статус проекта

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

Есть ли стандартный формат README?

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

Что еще вы думаете о написании README?

Ознакомьтесь со списком дополнительных ресурсов в Awesome README.

Как должен называться файл README?

README.md (или другое расширение файла, если вы решите использовать формат файла, отличный от Markdown). Традиционно оно пишется прописными буквами, чтобы быть более заметным, но это не имеет большого значения, если вы считаете, что строчные буквы выглядят лучше.

Что делать, если я с чем-то не согласен, хочу внести изменения или хочу оставить отзыв?

Пожалуйста, не стесняйтесь открывать тикеты или пулреквесты. Вы также можете отправить мне сообщение в Twitter.

Чтение мыслей?

Ученые и такие компании, как Facebook и Neuralink (предположительно), работают над этим. Возможно, в будущем вы сможете прикреплять к своим проектам копию своих мыслей и/или сознания. А пока сделайте README.

Что дальше?

Лицензия

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

Журнал изменений

Создать README вдохновлен Keep a Changelog. Журнал изменений — это еще один файл, очень полезный для проектов программирования.

Дополнительная документация

README — это важный, но основной способ документирования вашего проекта. В то время как у каждого проекта должен быть как минимум README, более активные могут также извлечь пользу из вики или специального веб-сайта с документацией. GitHub, Bitbucket и GitLab поддерживают поддержку вики параллельно с вашим проектом, и вот несколько инструментов и сервисов, которые помогут вам создать веб-сайт с документацией:

Содействие

Хорошим началом будет наличие раздела "Содействие" в вашем файле README. Другой подход — выделить ваши рекомендации в отдельный файл (CONTRIBUTING.md). Если вы используете GitHub и у вас есть этот файл, то любой, кто создаст задачу или откроет запрос на вытягивание, получит ссылку на него.

Вы также можете создать шаблон задачи и шаблон запроса на вытягивание. Эти файлы предоставляют вашим пользователям и соавторам шаблоны для заполнения информацией, необходимой вам для правильного ответа. Это помогает избежать таких ситуаций, как получение очень расплывчатых вопросов. И GitHub, и GitLab будут использовать шаблоны автоматически.

Make a README поддерживается Дэнни Гуо, размещается на GitHub с лицензией MIT и поддерживается Netlify.

Зачем нужен файл README?

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

Что такое файл README?

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

Когда вы создаете репозиторий или проект, GitHub предлагает вам файл сведений по умолчанию. Файл readme по умолчанию содержит имя репозитория и некоторые основные инструкции. Формат файла — «md», что означает документацию Markdown. Это легкий язык разметки, который можно легко преобразовать в текст.

Зачем нужен файл README?

Github стал платформой, на которой размещается большая часть открытого исходного кода, поскольку мир все больше и больше стремится к проектам и коду с открытым исходным кодом. Когда вы делитесь своим кодом со всем миром, может возникнуть проблема, заключающаяся в том, что они могут не понимать, как его использовать, или даже не понимать его. Вот тут и поможет файл readme. Файл readme используется для объяснения того, что загружено и как мы можем его установить или использовать. Он даже позволяет загрузчику добавлять изображения и видео, чтобы помочь читателю ориентироваться в проекте. Хорошо написанный файл readme более важен, если вы собираетесь показать эти проекты в своем резюме. Интервьюер может зайти в ваш проект, но не понять ни одного фрагмента кода. Но если есть файл readme, это поможет ему/ей лучше понять, для чего предназначен проект, какие языки/фреймворки использовались и как перемещаться по этому проекту. Хороший файл readme для вашего проекта имеет большое значение для того, чтобы произвести впечатление на вас на собеседовании. Недосказанная вещь о файлах readme заключается в том, что они даже помогают вам в будущем. Например: Если по какой-то причине через несколько месяцев после того, как вы покинули проект, была обнаружена ошибка, и компания или команда просит вас ее исправить. Вы полностью оторваны от реальности и понятия не имеете, с чего начать поиск. В этом случае пригодится файл readme.

Как написать хороший файл README?

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

Обновление: файл readme следует регулярно обновлять, чтобы он не конфликтовал с тем, что загружается в репозиторий. Если возможно, файл readme должен содержать сведения обо всех загруженных версиях и упоминать изменения/обновления проекта.
Кратко и ясно: файл readme не должен расширяться как эссе. В нем должно быть только самое необходимое и ничего больше. Она должна быть написана четко, имея в виду читателя, который собирается читать. Она должна быть написана простым языком, чтобы все могли понять. Лучше использовать маркеры или таблицы, чтобы лучше передать ваши мысли.
Подробно: в файле readme не должна быть пропущена никакая информация. Он должен содержать все необходимые детали, необходимые для понимания того, о чем проект и как его использовать.Например, если существует необходимость установить программное обеспечение для запуска проекта. Затем следует полностью указать версию программного обеспечения и технические конфигурации, необходимые для запуска проекта на их компьютере. Если вы чувствуете, что файл readme становится слишком длинным, вы можете разбить его и просто показать, что находится в контексте страницы или папки репозитория. Вы также можете предоставить ссылки на учебные пособия или инструкции по настройке системы или установке необходимого программного обеспечения, чтобы сделать ее краткой.
Пояснение не требует пояснений: пользователю не нужно обращаться к какой-либо другой статье, чтобы понять ваш файл readme. Он должен быть автономным, так как пользователь должен иметь возможность все понять, прочитав его. Так что лучше писать все простым языком, чтобы обычный читатель мог понять, потому что никогда не знаешь, кто это будет читать. Как разработчики, мы стараемся избегать написания основ, потому что это вполне нормально. Но лучше написать его, так как читатель может быть новичком в этой области.

Какой хороший шаблон для написания файла README?

В Интернете есть несколько макетов или форматов, которые помогут вам написать файл readme. Независимо от того, какой шаблон вы используете, убедитесь, что он соответствует всем пунктам, перечисленным выше. Итак, давайте просто посмотрим на один из них:

Если мы введем хэш фиксации SHA-1, он будет автоматически преобразован Github в ссылку.

Выдает ссылки в репозитории

Любая ссылка на любую проблему или запрос на включение автоматически преобразуется в ссылку.

Если есть необходимость упомянуть кого-то, кто внес свой вклад в проект в любом формате или сообщил о проблеме, вы можете легко упомянуть этого человека, используя символ «@», за которым следует имя. Вы также можете ссылаться на команды, используя ключевое слово @.

Любая введенная URL-ссылка преобразуется непосредственно в интерактивную ссылку.

Любой текст или слово, заключенное в ~~word~~, будет отображаться как перечеркнутое.

Теперь мы также можем вводить смайлики, чтобы выражаться лучше.

Некоторые распространенные смайлики:

SNo.	ShortCode	Emoji	ShortCode	Emoji< /td>
1	:ухмыляясь:	😀	8	:smiley:	😃
2	🙂	😄	9	😀	😁
3	:смех: или :удовлетворен:	😆	10	:sweat_smile:	😅
4	:rofl :	🤣	11	:радость:	😂
5	:slightly_smiling_faces:	🙂	12	:upside_down_face:	🙃
6	😉	😉	13	:blush:	😊
7	:невинный:	😇

Теперь, когда мы увидели, как писать в файл md. Давайте посмотрим, как файл readme предназначен для разных пользователей.

Для конечных пользователей: файл readme содержит ответы на вопросы об установке версий программного обеспечения, необходимых для запуска проекта. Шаги настройки, которые необходимо выполнить, чтобы все работало гладко. Файл readme также отвечает на вопросы, в основном основанные на том, какой фреймворк и язык кодирования использовались. Это также помогает пользователю понять, почему был использован определенный фреймворк вместо другого. Чем вдохновился владелец проекта, каким методом он решил проблему и многое другое.
Для нашей собственной разработки: в файле readme представлены два хороших варианта использования. Во-первых, если он написан до начала разработки, он помогает разработчику, действуя как дорожная карта или трекер, чтобы он знал, что осталось сделать в жизненном цикле проекта. Во-вторых, это помогает разработчику лучше понять код, который он мог бы написать несколько лет назад, когда возникает необходимость в его повторном просмотре и устранении ошибок. Это очень помогает, так как требуется много времени, чтобы понять код, когда вам нужно просмотреть миллионы строк кода, которые вы, возможно, написали несколько лет назад. Файл readme поможет вам определить, где находится каждый раздел кода, и поможет вам найти фрагмент кода, который вы искали. Это здорово экономит время, когда проблема критична и ограничена во времени.
Для других разработчиков: файл readme служит той же цели, что и другие разработчики, просматривающие код, и помогает им понять, где находится каждый раздел кода и на какой странице содержится логика. Это помогает, когда есть проблема в коде, и другой разработчик пытается решить эту проблему. Он может легко просмотреть код и найти проблему. Точно так же, если другой разработчик пытается улучшить код, то хороший файл readme поможет ему в этом.

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

Надеюсь, это помогло вам немного узнать о файле Readme. Чтобы узнать больше о программировании и других связанных с ним понятиях, ознакомьтесь с курсами Great Learning Academy.

Хиллари Ньякунди

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

Долгое время, будучи новичком, я ничего не делал со своей учетной записью. Но затем, из-за моей страсти к технологиям, я начал следить за другими разработчиками и проверять их работу на GitHub. И я заметил, что у них есть кое-что общее: у всех у них были классные проекты, и они вносили свой вклад в открытый исходный код, но их проекты также имели подробные файлы README.

Поэтому мой интерес к тому, что такое README, вырос, и я решил попробовать добавить его в свои проекты. Не буду врать – я сделал это в спешке, не зная, как это должно быть сделано. И, честно говоря, это было совсем не здорово. Посмотрите ЗДЕСЬ.

И так оно и оставалось какое-то время. Но с практикой и непрерывным обучением я смог перейти на более качественную документацию, такую как ЭТА, которая улучшила взаимодействие с проектом и помогла другим разработчикам принять участие.

Также важно отметить, что хороший файл README поможет вам выделиться среди большого числа разработчиков, размещающих свои работы на GitHub.

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

Что такое файл README?

Проще говоря, мы можем описать файл README как руководство, которое дает пользователям подробное описание проекта, над которым вы работали.

Его также можно описать как документацию с инструкциями по использованию проекта. Обычно в нем есть инструкции по установке и запуску проекта.

Для вас как разработчика важно знать, как документировать свой проект, написав README, потому что:

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

Хороший писатель обладает не только своим духом, но и духом своих друзей.

Во время работы над проектом помните, что вам понадобятся другие разработчики, чтобы понять ваш код и то, что он делает. Так что сопроводить его дополнительным руководством будет очень полезно.

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

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

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

Видите ли, насколько мощным является хорошо написанный README и как он может изменить ваш проект.

Итак, давайте начнем с того, как написать его и для вас.

Как написать хороший README — пошаговое руководство

Очень важно отметить, что не существует единственно правильного способа структурировать хороший файл README. Но есть один очень неверный способ — вообще не включать README.

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

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

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

Вот несколько наводящих вопросов, которые помогут вам:

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

Что включить в README

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

Это название проекта. Он описывает весь проект в одном предложении и помогает людям понять, какова основная цель и задача проекта.

2. Описание проекта

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

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

Качество описания в README часто отличает хороший проект от плохого. Хороший использует возможность объяснить и продемонстрировать:

Что делает ваше приложение,
Почему вы использовали используемые технологии,
Некоторые проблемы, с которыми вы столкнулись, и функции, которые вы надеетесь реализовать в будущем.

3. Оглавление (необязательно)

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

4. Как установить и запустить проект

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

Предоставьте пошаговое описание того, как настроить и запустить среду разработки.

5. Как использовать проект

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

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

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

6. Включить кредиты

Если вы работали над проектом в команде или в организации, укажите соавторов/членов команды. Вы также должны включить ссылки на их профили GitHub и социальные сети.

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

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

7. Добавить лицензию

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

У нас есть разные типы лицензий в зависимости от типа проекта, над которым вы работаете. В зависимости от того, что вы выберете, будет зависеть вклад, который получит ваш проект.

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

Дополнительные разделы README

8. Значки

Значки необязательны, но их использование — это простой способ показать другим разработчикам, что вы знаете, что делаете.

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

Ниже приведен снимок экрана одного из моих проектов, показывающий, как можно использовать значки:

Преимущество этого раздела в том, что он автоматически обновляется сам.

Не знаете, где их взять? Проверьте значки, размещенные на shields.io. У них есть масса значков, которые помогут вам начать работу. Возможно, сейчас вы не понимаете, что они представляют собой, но со временем поймете.

9. Как внести свой вклад в проект

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

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

Некоторые из наиболее распространенных рекомендаций включают Соглашение с участниками и Руководство по содействию. Эти документы окажут вам необходимую помощь при установке правил для вашего проекта.

10. Включить тесты

Приложите дополнительные усилия и напишите тесты для своего приложения. Затем предоставьте примеры кода и способы их запуска.

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

Дополнительные баллы

Вот еще несколько моментов, на которые следует обратить внимание при написании файла README:

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

Подведение итогов

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

На данный момент я уверен, что вы в состоянии добавить интерактивное и информативное руководство к вашему следующему или даже существующему проекту и сделать ваш проект выдающимся.

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

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

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

Читайте также: