Структура спецификации или README — Примеры

Пример 1 — Перепишите первый экран README

README небольшого инструмента открывается историей проекта: перепишите первый экран так, чтобы «что», «зачем» и инструкция запуска появлялись до любой прокрутки, а справочный материал перешёл в таблицу.

# Order Exporter

У команды финансов уже несколько лет есть ночной экспорт. Его дважды
переделывали. Этот документ описывает текущую реализацию и решения за ней.
Команда поддерживает и другие инструменты, а полную историю можно найти
ниже...

(дальше установка и настройка, тремя экранами ниже)

Решение

# Order Exporter
Копирует заказы в CSV для ночного задания финансов. Работает по расписанию.
Владелец: Прия, платформа поддержки. Написано в сентябре 2026.

Локальный запуск
  ...
Настройка         переменная | значение | по умолчанию
Частые сбои       симптом | причина | исправление
Заметки о дизайне почему он имеет такую форму

«Что» и «зачем» стоят в первых двух предложениях: читатель знает, кого спрашивать и когда документ написан. А то, что ищут, лежит в таблице. Обычная ошибка — начинать с контекста, который был у автора, вместо ориентира, нужного читателю.

Пример 2 — Назовите ответ в заголовке и ограничьте объём

В спецификации возвратов стоят заголовки-темы, поэтому по ним не понять, к какому выводу приходит любой раздел, и нигде не сказано, чего работа не покрывает; исправьте и то, и другое.

Варианты заголовков для спецификации
  Соображения
  Механика возвратов
  Открытые вопросы

Решение

# Спецификация возвратов
Владелец: PM. Написано в сентябре 2026.
Проблема: возвраты занимают 1,5 дня; 6% выдаются неверно повторно.

Используйте книгу учёта как источник истины    (было: Соображения)
Требования   REQ-REF-01 ... по одной проверяемой строке на каждое
Что не входит мультивалютность, частичные возвраты, возвраты подарочных карт
Ограничения   существующая книга учёта остаётся источником истины
Открытые вопросы кто отвечает за отчёт о сверке?

Теперь заголовок называет вывод раздела, так что решение найдёт даже тот, кто только пробегает документ глазами, а список «что не входит» снимает больше споров, чем любой другой раздел. Обычная ошибка — заголовок вроде «Соображений»: о принятом решении он читателю ничего не сообщает.