README считается полезным, когда другой человек может запустить проект без переписки с автором. Для этого нужны точная папка, команда, адрес и ожидаемый результат. Длинное описание идеи не компенсирует пропущенный шаг запуска. Сделаем комплект минимальной страницы и инструкции к нему.
Мини-проект и инструкция для другого человека
index.html
<!doctype html>
<html lang="ru"><meta charset="utf-8"><title>Дистанции</title>
<p id="total"></p><script src="./app.js" defer></script></html>app.js
const distances = [3, 5];
const total = distances.reduce((sum, value) => sum + value, 0);
document.querySelector('#total').textContent = `Всего: ${total} км`;README.md
# Список дистанций
Локальная учебная страница. Данных пользователей и внешнего API нет.
## Требования
Python 3 с модулем http.server и современный браузер.
## Запуск
1. Откройте терминал в папке с index.html.
2. Выполните: python -m http.server 8000
3. Откройте: http://localhost:8000
4. Ожидается строка: Всего: 8 км.
5. Для остановки сервера нажмите Ctrl+C.
## Файлы
index.html — разметка и подключение app.js.
app.js — учебные данные и вывод.
## Проверка
Измените [3, 5] на []: ожидается 0 км.
Верните исходные данные после проверки.
## Ограничения
Это локальное демо без регистрации, хранения и публикации в интернете.
Не добавляйте реальные личные данные в учебный файл.
## Если не запускается
Проверьте папку запуска, порт и ошибки Console/Network.
Если порт занят, используйте другой и измените адрес в браузере.| Что сравнить | На что смотреть | Что сделать |
|---|---|---|
| Назначение | Что делает проект и чего ожидать | Одно конкретное предложение |
| Запуск | Откуда и какую команду выполнить | Привести воспроизводимые шаги |
| Проверка | Как понять, что всё работает | Указать наблюдаемый результат |
| Границы | Чего в демо нет | Не обещать сервер или сохранение без реализации |
Проверьте инструкцию в чистом сценарии
Закройте прежнюю вкладку, откройте новую папку с тремя файлами и пройдите шаги заново. Если для запуска понадобилось вспомнить настройку, которой нет в README, добавьте её. Не советуйте установить пакет, который код не использует. Для примера локальная команда нужна только как простой способ открыть страницу по HTTP, а не как рабочий production-сервер.
- Сверить имена файлов с реальным комплектом.
- Проверить ожидаемую сумму и пустой массив.
- Проверить остановку локального процесса.
- Не включать в инструкцию пароли и личные ключи.
Вопросы и ответы
Нужны ли скриншоты?
Иногда помогают, но для этого примера точный текст результата достаточен. Картинка не заменяет команду запуска.
Надо ли описывать каждую строку кода?
README отвечает за использование проекта. Подробный учебный разбор может находиться в статье или отдельной документации.
Почему важно написать про отсутствие сервера?
Локальный показ страницы и реальный сервис с хранением данных имеют разные возможности. Читатель должен понимать границы.
Когда обновлять README?
Вместе с изменением команды, структуры или ожидаемого поведения. После правки снова выполните инструкцию.
