Существует острая необходимость в правильном файле README в каждом проекте, над которым вы работаете. Здесь должна содержаться очень основная, но ключевая информация о проектах, но не только это. Хороший README получается, если в нем содержится немного больше, чем основная информация о проекте. Что именно? Мы рассмотрим это в этом документе.
Технологии
Обычно README, с которым мы работаем, имеет расширение .md
, обозначающее файл Markdown. Markdown — это то, что позволяет нам форматировать текст определенным образом. Мы будем придерживаться этого и предположим, что для удобства в файле README используется Markdown. Обратите внимание, это не обязательно так.
Разделы
Заголовок
Начните README со строки названия проекта, например: # Example Project
. Это очевидно, но необходимо. #
помечает данную строку как заголовок в Markdown.
Краткое содержание
Здесь необходимо указать основную информацию о проекте. Что это за компонент системы? Например — API, Worker, фронтенд, библиотека. Какие функции он включает? Например — это API выставления счетов для системы foobar. Некоторый дополнительный контекст — кто заинтересованные стороны (для кого предназначен проект), какая бизнес-потребность/идея стоит за этим приложением, кто является действующими лицами, конечными пользователями, несколько слов о проекте с точки зрения бизнеса. Резюме также должно содержать и использовать формулировку, тесно связанную с Доменом проблемы/потребности, которую решает проект.
Стек технологий
Этот раздел должен содержать наиболее важные пакеты, используемые для сборки приложения, сторонние зависимости, сервисы и т. д.
Это позволит читателю получить быстрое представление о зависимостях приложений и используемых технологиях, решенных проблемах.
Не следует забывать связать используемые технологии с соответствующими веб-сайтами, ресурсами, чтобы не было двусмысленности.
Настройка локальной разработки
Запишите список шагов, необходимых для запуска проекта в разработку локально на компьютере разработчика. Помимо этого, вы также должны добавить список часто выполняемых операций, таких как очистка базы данных; (пере)установить проект с нуля; перенести базу данных. То же самое и со знаниями по конкретным проектам — этот раздел — хорошее место для таких вещей. Например, обработка l10n, i18n с помощью стороннего сервиса, такого как PhraseApp или OneSky.
Раздел настройки локальной разработки должен быть подготовлен, имея в виду менее технических людей, поскольку его могут использовать заинтересованные стороны, которые не всегда разбираются в технологиях. Кроме того, настройка локальной разработки должна быть максимально автоматизирована.
Развертывание
Кратко опишите, как развертывается приложение, где искать более подробное объяснение, если нужно, какова настройка развертывания или несколько слов о CI/CD.
Авторы
Оставьте какой-то список людей, которые внесли свой вклад в проект или являются ключевыми людьми в контексте этого проекта. Это может быть полезно при переходе от одного проекта к другому через некоторое время, так как позволяет очень быстро идентифицировать держателей контекста.
Первоначально опубликовано на https://grski.pl 28 ноября 2022 г.