Многие программисты лихо управляются с кодом и знают мельчайшие подробности своих проектов. Но некоторым из них (в том числе и мне) недостаёт коммуникативных навыков.
Удивительное дело: программист может потратить час на подгонку внутренних и внешних отступов для одной-единственной кнопки и не найти каких-то 15 минут на файл Readme описания проекта.
Надеюсь, вы уже знаете, что такое файл readme.md и для чего он нужен. На всякий случай попробую объяснить.
Что такое Readme.md?
README (буквально означает «прочти меня») — это первый файл, который нужно читать, получив доступ к проекту на Github или любой Git-хостинговой площадке. Этот файл в первую очередь и предлагается вниманию пользователя, когда он открывает здесь репозиторий того или иного проекта. Такой файл содержит кучу полезной информации, так что его вполне можно рассматривать как справочное руководство по проекту.
Посмотрите, где у нас здесь файл Readme:
Файл Readme.md находится в корневой папке репозитория и автоматически отображается в каталоге проекта на github.
Как Оформить README-Файл На GitHub | Основы Markdown
Расширение .md — это сокращение от слова markdown. Это язык разметки для форматирования текста. Его используют (как и язык разметки HTML) для нормального отображения документов.
Вот как выглядит файл разметки на github (здесь использован VSCode, который одновременно показывает нам файлы разметки и в режиме предварительного просмотра):
Здесь можно найти официальный гайд Github для формата разметки на тот случай, если вам захочется основательно разобраться в языке разметки.
Зачем тратить время на Readme?
Разъяснения закончены, теперь перейдём к делу. Итак, потратив несколько часов на проект, вы выкладываете его на GitHub в надежде, что кто-нибудь (коллеги, потенциальные работодатели или бывшая) его увидит. Вы правда думаете, что они станут заглядывать в root/src/app/main.js , чтобы оценить вашу прекрасную логику? Серьёзно?
Генерирование документации для ваших компонентов
Кроме readme проекта, для понятной кодовой базы необходимо документирование компонентов, благодаря которому упрощается сопровождение кода и повторное их (компонентов) использование. Для автоматического генерирования документации к компонентам, выкладываемым на bit.dev, можно использовать такие инструменты, как Bit (Github).
Источник: medium.com
Что такое README-файл?
Эти файлы README можно просматривать с помощью двадцать шесть существующего (-их) прикладных (-ого) программных (-ого) средств (-а), как правило, LibreOffice, разработанного The Document Foundation. Оно связано с один основным (-и) типом (-ами) файла (-ов), но часто встречается в формате Readme Text Document File. Чаще всего файлы README классифицируют, как Text Files.
Markdown — напиши README за 2 минуты
Расширение файла README поддерживается Windows, Mac и iOS. Данные типы файлов можно найти в основном на настольных компьютерах и некоторых мобильных устройствах. Рейтинг популярности основного типа файла README составляет «Низкий», что означает, что эти файлы встречаются на стандартных настольных комьютерах или мобильных устройствах достаточно редко.
Интересно узнать больше о расширении файла README? Для того, чтобы узнать о программе, открывающей файлы README, а также ознакомиться с другими советами по устранению неполадок, рекомендуется обратиться к подробной информации о файле, представленной ниже.
Источник: www.solvusoft.com