Существует острая необходимость в правильном файле 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 г.