для чего нужен readme md
Как написать хороший README для вашего проекта на GitHub
Если вы читаете эту статью, это, вероятно, означает, что вы уже размещаете репозитории на GitHub и, возможно, даже вносите свой вклад в открытый исходный код. А если вы используете GitHub, то вам нужно писать хорошую документацию для своих проектов, чтобы помочь другим понять их.
Когда я впервые зашла на Github, честно говоря, я понятия не имела, что такое файл README (хотя я видела его в проектах других людей).
Во-первых, зачем мне хороший файл README?
Файл README — это руководство, которое дает пользователям подробное описание проекта, который вы разместили в своем репозитории.
Возможно, вам интересно, зачем тратить время на написание хорошего README. Вот несколько причин, которые помогут убедить вас в том, что это хорошая идея:
README должен ответить на следующие вопросы: что, почему и как:
Если в вашем проекте много функций, подумайте о том, чтобы добавить раздел «Возможности» и перечислить их здесь.
Как написать хороший файл README
Вот шаги, которые вы должны предпринять, чтобы написать README.
Включите название вашего проекта
Это название проекта. Он описывает весь проект одним предложением и помогает людям понять, какова основная цель и цель проекта.
Напишите описание
Ваше описание — чрезвычайно важный аспект проекта. Хорошо составленное описание позволяет продемонстрировать свою работу другим разработчикам, а также потенциальным работодателям.
Как установить ваш проект
Если ваш проект представляет собой программное обеспечение или приложение, которое требует установки, вы должны включить шаги, необходимые для установки вашего проекта. Предоставьте пошаговое описание того, как запустить среду разработки.
Как использовать ваш проект
Предоставьте инструкции и примеры, чтобы пользователи/участники могли использовать проект. Это упростит им задачу в случае, если они столкнутся с проблемой — у них всегда будет место для ссылки. Вы также можете вставить скриншоты, чтобы показать примеры работающего проекта.
Если вы работали над проектом как команда или организация, перечислите своих соавторов / членов команды. Вы также должны включить ссылки на их профили GitHub.
Разметка README.md в GitHub
Для описания проектов на GitHub используется README.md, который пишется на языке разметки markdown. Что и как поддерживается расписано ниже.
Заголовки
Списки
Маркированный
Задать маркированный список можно несколькими символами:
Нумерованный
Если же Вам нужно число с точкой, но не нужен список, то можно сделать так:
Смешанный
Нумерованный и маркированный списки можно смешивать:
Ссылки
Либо просто вставить ссылку, либо дополнительно задать текст ссылки (пробела между скобками быть не должно):
Можно выводить через «константу», которую можно задать в любом месте, обычно их задают в конце документа.
[example site]
[example site]:http://example.com
Цитаты
> Цитата
> > Вложенная цитата
Начертание шрифта
**bold**
*italic*
***bold italic***
_italic too_
**Можно использовать _курсив_ внутри жирного текста.**
Вставки кода
Можно использовать `light-code` внутри строки
Изображения
Описание крайне похоже на описание ссылки, за исключением лишь восклицательного знака в начале.
Собственный open source проект. Часть 3: документация
Представляем вам перевод третьей статьи из серии «Собственный open source проект» — «Open Source Series: Documentation». Для тех, кто не читал предыдущие, вот список:
Первые две статьи цикла предназначались для людей, обдумывающих возможность создания собственного проекта. Я хотел, чтобы люди понимали, чего следует ждать, а также знали, какими должны быть их первые шаги в мире open source.
Эта статья пригодится не только людям, планирующим начать собственный проект, но и людям, которые уже поддерживают таковой.
Для целей этой статьи мы исходим из того, что у вас уже есть open source проект, он доступен на GitHub и его легко можно получить при помощи какого-нибудь реестра пакетов.
Итак, приступим
Проект с открытым исходным кодом, не имеющий документации, это мертвый проект.
Он мертв, потому что никто не захочет погружаться в разбор вашего кода, чтобы понять, как его можно использовать. И дело даже не в том, что без документации людям не понятно, как пользоваться проектом, дело в том, что без нее никто даже не будет знать, для чего вообще предназначен ваш проект.
В общем, «для чего?» и «как?» это и есть два основных вопроса, ответы на которые должны содержаться в вашей документации проекта. Это ее основа и обязательная часть.
Описание
Описание проекта это первое, что видит любой посетитель GitHub-репозитория. Поэтому хорошее описание должно коротко давать ответ на вопрос «для чего?» в отношении этого проекта. Например:
A declarative, efficient, and flexible JavaScript library for building user interfaces. («Декларативная, эффективная и гибкая JavaScript-библиотека для создания пользовательских интерфейсов»).
Чтобы редактировать описание, нужно кликнуть кнопку «Edit» в верхнем правом углу вашего репозитория:
README.MD
README.MD это файл в корневом каталоге вашего проекта, написанный с использованием синтаксиса Markdown. Этот файл содержит всю информацию о вашем проекте, которая может понадобиться посетителю репозитория.
Файл README должен содержать детальное описание проекта (ответ на вопрос «для чего?») и очень подробные инструкции по его использованию (ответ на вопрос «как?»). Эти инструкции должны затрагивать каждую часть публичного API, желательно — с примерами использования.
Несколько советов по написанию хорошей документации API:
README может содержать следующие вещи (хотя это уже не обязательно):
Бейджи
Бейджи это довольно хороший способ представить необходимую информацию о вашем проекте (статус сборки, версия, лицензия, используемые инструменты) визуально.
Вообще есть широкий выбор источников бейджей, но я советую пользоваться shields.io: там есть значки буквально для чего угодно.
Добавить бейдж в свой файл README очень просто:
Бейджи обычно располагаются вверху файла README, прямо перед подробным описанием. Вот как это выглядит:
Тесты
Справка по API это хорошо, но ничто не сравнится с настоящим кодом, где используются ваши публичные API.
Один из лучших способов дополнить вашу документацию — иметь хорошее покрытие кода описательными тестами. Иногда тесты объясняют код лучше любой документации.
Итоги
В этой части мы затронули только самую основную документацию. На самом деле в ней может быть не только README или описание проекта. Например, по мере роста проекта и появления каких-то проблем (issues) последние становятся неотъемлемой частью документации.
Но файл README, описывающий публичный API, это абсолютный минимум, необходимый для каждого достойного проекта с открытым исходным кодом.
Составляем идеальный файл README
Перевод статьи «How to write a kickass README».
Вероятно, README это самая простая часть документации любого проекта с открытым исходным кодом. Хороший README сообщает людям не только о том, что делает проект и для кого он предназначен, но и о том, как именно нужно использовать проект и как принять участие в его разработке.
Если не уделить должного внимания составлению хорошего README, где объяснялось бы, как пользоваться проектом и для чего он вообще создан, такой проект не оправдает себя в качестве именно open source проекта, поскольку другие разработчики с меньшей вероятностью станут в нем участвовать.
Что такое README?
Доказано, что файлы README появились уже в 1970-е. Самый старый найденный мной экземпляр README датируется 27 ноября 1974 года (создан для DEC компьютера PDP-10). Есть много версий, почему файл первичной документации принято называть именно README, но основных среди них две:
Что нужно включить в файл 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, я советую воспользоваться следующими источниками:
Русские Блоги
README.md учебник по GitHub
README.md учебник по GitHub
Недавние к этомуREADME.mdФайл довольно интересный. Я написал этот пост, чтобы помочь большему числу студентов, которые не знают, как писать файлы README.
Я создал «тест» для этой статьи на GitHub, чтобы каждый мог проверить код и конкретный эффект:https://github.com/guodongxiaren/test
Начать редактирование README
Откройте проект на вашем GitHub, мы можем напрямую отредактировать ваш файл README онлайн, если у вас уже есть этот файл, щелкните его непосредственно в каталоге файлов, если у вас его еще нет, нажмите кнопку справа от названия проекта Чтобы добавить новый файл:
Затем вы открываете страницу редактирования, в левом верхнем углу области редактирования есть область для заполнения имени файла, обратите внимание на добавление суффикса.md
Если у вас уже есть этот файл и вы хотите отредактировать его еще раз, то после щелчка по файлу в папке с файлами вверху появится панель инструментовEdit
Затем прокрутите экран вниз, если это новый файл, будетCommit new fileКнопка не может быть нажата, если нет содержимого. Если это новое редактирование старого файла, то эта кнопка показывает Commit changes
Напишите все, что вы хотите отправить этот новый файл, а затем нажмите кнопку «Изменить», чтобы открыть его снова. Вы найдете изменения в верхнем левом углу области редактирования.
Код выбран по умолчанию, это наш режим редактирования. Нажмите «Просмотр», чтобы отобразить текущий эффект отображения в режиме реального времени.
Хорошо, теперь официально начать редактировать этот файл
О названии
Заголовок записывается в начале стандартного файла README, который называется заголовком 。
Средний заголовок на один уровень ниже, чем большой, что означает, что он отображается меньше, чем большой заголовок.
Добавьте символ подчеркивания ниже текста, затем текст выше становится средним заголовком, и количество подчеркиваний не ограничено.
Если вы введете только знак равенства =, но над ним нет текста, будет отображаться только прямая линия. Если в верхней части есть текст, но вы хотите отобразить только горизонтальную линию и не хотите, чтобы текст в верхней части отображался в заголовке, вам нужно добавить пустую строку между знаком равенства = и текстом.
Заполнение пустых строк: это очень распространенное использование. Если вы не хотите, чтобы два разных макета были смещены вместе, вам необходимо заполнить пустую строку между двумя макетами.
Кроме того, есть также обозначение уровня для заголовка, которое разделено на шесть уровней, и отображаемый размер текста последовательно уменьшается. Различные уровни идентифицируются по количеству хэштегов #. Заголовок первого уровня имеет #, заголовок второго уровня имеет два # и так далее.
Фактически, упомянутые выше заголовки и средние заголовки соответствуют первичному и вторичному заголовкам соответственно. То есть размер большого заголовка такой же, как заголовок первого уровня, а размер среднего заголовка такой же, как заголовок второго уровня.
Показать текст
Обычный текст
Текст, введенный напрямую, является обычным текстом. Следует отметить, что если вы хотите изменить строку, вы не можете напрямую использовать возврат каретки для изменения строки, вам нужно использовать
(или
). Какой тег в HTML 。На самом деле, уценка поддерживает некоторые HTML-теги, вы можете попробовать.Конечно, если вы используете html для полной записи, он потеряет свое значение: в конце концов, уценка не предназначена специально для front-end, но если она дает только общие эффекты, она будет гораздо более краткой, чем html.
Эффект заключается в следующем:
Кроме того, для отображенияГиперссылкаЕсли это так, просто введите URL этой ссылки напрямую. Дисплей автоматически станет связываемой формой.
Маленький совет с пробелами
Однострочный текст
Используйте два символа табуляции для получения однострочного текста.