README.txt

git-README.txt

==> https://devman.org/encyclopedia/tutorial/tutorial_readme/

Что должно быть в README

1. Короткое описание проекта
Для тех кто заблудился оставляют вводное слово о проекте. Просто и доходчиво объясняют в чем польза от этого кода.

2. Требования к окружению
Обычно здесь указывают тип операционной системы или минимальную версию интерпретатора Python. Для сайтов —важно знать поддерживаемые версии браузеров и формат устройств: мобильники, планшеты или desktops.

3. Как установить
Раздел отвечает на вопрос "Что нужно сделать перед запуском программы?" и содержит инструкции по развертыванию проекта. Самый удобный формат — это команды bash с коротким пояснением к ним. Пользователь копирует команды в консоль и быстро их запускает.
Оформленный код попадается на глаза даже при беглом чтении, что крайне удобно.

4. Примеры запуска скриптов
Если речь идет о консольной утилите, то полезно показать как в консоли выглядит результат работы скрипта в случае штатной ситуации.
Если у проекта есть скрипты c тестами или другие инструменты для разработчиков, то об этом тоже полезно написать, привести примеры их запуска.

5. Примеры использования программного API
Если проект поставляется в виде библиотеки и используется из других скриптов посредством import, то стоит описать доступные функции, классы и константы. Нагладнее всего получается это сделать на примерах кода, поэтому их должно быть много.
Если проект большой то документацию часто выносят на отдельный сайт с удобной навигацией и поиском. Часто используют сервис Read the Docs.