Ответ: отличный readme-файл. Он идеально сочетает в себе документацию, общие сведения о проекте, часто задаваемые вопросы и инструкцию по внесению правок. Readme-файл похож на руководство, в нем разработчики детально рассказывают о проекте. Он дает полное понимание того, куда движется проект, объясняет, что это за ПО, и зачем оно нужно. В нем указаны предварительные условия, которые помогают новым участникам проекта быстрее включиться в работу, а также инструкция по развертыванию ПО в среде эксплуатации. То есть упрощается коммуникация. А значит, повышается эффективность. Все, как мы любим в Инфомаксимум.
К примеру, вы потратили несколько часов, а может быть, и бессонных ночей на проект и выкладываете результат на GitHub в надежде, что коллеги или потенциальные работодатели его увидят. Но вряд ли кто-то станет тратить время и разбираться в логике вашего кода, если у вас нет описания и понятной документации.
Хороший readme.md помогает привлечь разработчиков, которые будут вносить вклад в проект.
Поэтому золотое правило для программиста – любой проект должен начинаться с readme-файла. Обязательно добавьте его в корневой каталог вашего проекта, чтобы его было видно на GitHub.
Что должно быть в readme:
- Краткое описание проекта. Просто и доходчиво: в чем польза этого кода.
- Требования к окружению. Тип операционной системы или поддерживаемые версии браузеров.
- Как установить. Инструкции по развертыванию проекта.
- Примеры запуска скриптов. Как в консоли выглядит результат работы скрипта в случае штатной ситуации?
- Примеры использования программного API. Желательно описать доступные функции, классы и константы.
