2learn

Структура спецификации или README

Что это такое

Структура — это порядок, в котором документ отвечает на вопросы читателя: что это, стоит ли мне это учитывать, как этим пользоваться, что делать, когда оно ломается, и где живут подробности. README и спецификация отвечают на слегка разные вопросы, однако проваливаются одинаково. Ход всегда один и тот же: наверх выносят контекст, который был у автора, вместо ориентира, нужного читателю.

Почему это важно

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

Ключевые идеи

README начинается с «что» и «зачем» в одну строку

Дальше идут запуск, потом использование, потом раздел о том, где просить помощи; читателю, который прикидывает, брать ли эту вещь, хватит первых двух предложений и ничего больше.

Order Exporter
Копирует заказы в CSV для ночного задания финансов. Работает по расписанию.

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

Спецификация начинается с проблемы, затем идёт поведение

Сначала — что решают и для кого, затем требования в проверяемой форме, затем ограничения и то, что не входит в объём. Больше всего споров снимает именно раздел «что не входит».

  Проблема и цель
  Требования          REQ-PAY-014 ... (по одному в строке, проверяемые)
  Что не входит       мультивалютность, частичные возвраты
  Ограничения         существующая книга учёта остаётся источником истины
  Открытые вопросы    кто отвечает за отчёт о сверке?

Ставьте ответ перед рассуждением

Кому нужно рассуждение, тот прочитает дальше, а кому нужен ответ, тот не должен до него добираться. Заголовок, который называет ответ, — «Используйте книгу учёта как источник истины», — стоит больше заголовка, который тему только называет.

Для справочного материала используйте таблицы и списки

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

Указывайте, когда документ написан и кто за него отвечает

Дата и имя — наверху. Без них читатель не может судить, актуален ли документ: он либо зря ему доверится, либо пройдёт мимо.

Практика

Перепишите первый экран одного README

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

Готово, когда: коллега, никогда не видевший проекта, по одному первому экрану скажет, что тот делает и как его запустить.

Добавьте раздел «что не входит»

Возьмите одну спецификацию и добавьте в неё явный список из пяти пунктов, которые в неё не входят.

Готово, когда: читатель назовёт две вещи, которых от этой работы ждать не следует.

Частые ошибки

  • Предыстория до ответа — до полезного читатель не доходит и уходит; исправить: начинайте с «что» и «зачем».
  • Заголовки-темы — «Соображения»; к какому выводу приходит раздел, читателю не понять; исправить: называйте ответ в заголовке.
  • Справочный материал в прозе — настройку, зарытую в абзацах, не просмотреть глазами; исправить: таблицы и списки для всего, что ищут.
  • Нет раздела «что не входит» — ожидания растут, пока работа не перестанет их покрывать; исправить: перечислите, что сюда намеренно не входит.
  • Нет даты или владельца — судить об актуальности читателю не по чему; исправить: поставьте имя и дату наверху.

Что читать дальше

Разобранные примеры

Файлы cookie аналитики ставятся только с вашего согласия. До вашего выбора ничего не загружается и никуда не отправляется.