Спецификации в заказной разработке: оставлять ли Excel — как выбрать формат сдачи

«Получили исправленную спецификацию, так и не поняли, что изменилось, и всё равно поставили отметку о приёмке»

«Собрались заказать доработку — а сданная спецификация в Excel совсем не похожа на нынешние экраны»

«От компании-разработчика пришла спецификация в Excel «в клеточку» — так и должно быть?»

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

Критики Excel «в клеточку» в интернете много, но почти вся она про то, насколько это неудобно как внутренний документ команды разработки. Здесь другой ракурс: спецификация, которую сдают заказчику в заказной разработке. Что в ней ломается и какой формат выбирать — на языке договорной практики: приёмка, изменение спецификации, сопровождение. Текст рассчитан и на заказчика, и на компанию-разработчика, которая сдаёт документы.

1. Сначала вывод

Кратко, о чём речь.

• Формат сдаваемой спецификации выбирают не по критерию «удобно ли писать во время разработки», а по тому, сможет ли заказчик её ревьюить, выдержит ли она приёмку, можно ли показать различия при изменении спецификации и пригодится ли документ через несколько лет на сопровождении
• Вывод — не «отказаться от Excel», а «убрать клетчатку и использовать каждый формат по назначению». Текст — в Word, таблицы — в обычных таблицах Excel, схемы — в инструменте для схем, фиксация согласия — в PDF
• Прежде чем спорить о формате, в договоре (указание сдаваемых материалов в отдельном договоре) нужно решить, какие документы входят в результат работ и получите ли вы редактируемый оригинал

Если свести рекомендуемый формат по типу документа в таблицу, получится так.

Ниже — почему именно так.

На схеме сплошная линия обозначает отношение, которое выполняется всегда, а пунктирная — условное отношение (условия указаны в пояснении к каждому отношению на странице сведений). Полный список отношений (всего 18, с доказательствами и степенью уверенности) и определения основных понятий собраны на странице сведений карты знаний (на японском). Данные: JSON-LD / Turtle

2. Что не так со спецификацией в Excel «в клеточку» как с результатом работ

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

Для внутреннего документа компании это проблема тех, кто его написал. Когда документ сдают как результат работ, картина другая: спецификация — это результат работ, за который заказчик платит, предмет приёмки и актив, которым будут пользоваться годы. С этой точки зрения у Excel «в клеточку» такие слабые места.

2.1 На приёмке документ нельзя нормально проревьюить

В Excel «в клеточку» нет практичного показа различий вроде режима исправлений Word. Точнее: в совместном редактировании Microsoft 365 есть история изменений ячеек («Показать изменения» и журнал версий), есть и инструменты вроде Spreadsheet Compare для сравнения книг. Но отслеживаются в основном значения ячеек и формулы. Текст внутри фигур и надписей, которыми клетчатка пользуется постоянно, туда не входит. А если файлы гоняют вложениями по почте, история совместного редактирования и вовсе не работает.

В итоге, получив исправленную версию по замечаниям ревью, заказчик глазами ищет, «что же изменилось». Перечитывать десятки листов целиком на каждом круге нереально, поэтому отметку о приёмке ставят по принципу «наверное, исправили».

Это выхолащивание приёмки. Приёмка — процедура «проверить, что результат работ соответствует согласованному содержанию, и принять его». Когда она становится формальностью, позже всплывает беспредметный спор: «вы же приняли» против «это сдали не в виде, который можно было проверить».

2.2 Не остаётся записи о согласованном изменении спецификации

В ходе разработки спецификация обязательно меняется. Если документ — Excel «в клеточку», переписка по изменениям часто превращается в гору копий файлов. Имя вроде спецификация_v2_финал_испр(2).xlsx многим знакомо.

Проблема в том, что потом нельзя установить, какая версия — «версия, согласованная обеими сторонами». Когда спорят о дополнительных расходах или сроках, основанием служит согласованный документ. Если непонятно, какой это файл, остаётся спор без доказательств.

2.3 На сопровождении документ расходится с реализацией

Обновлять клетчатку дорого, поэтому после сдачи при доработках её всё реже трогают. Боятся сломать вёрстку и не трогают вовсе; текст внутри фигур не находится поиском, и правки пропускают. Через несколько лет накапливается состояние «спецификация вроде есть, но никто не знает, совпадает ли она с системой».

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

2.4 Заказчик не может этим пользоваться

Вёрстка под печать на экране читается плохо. Содержание размазано по множеству листов и фигур, полнотекстовый поиск работает слабо, и поиск «где было написано вот это требование» занимает время. Заказчику трудно и вторично использовать документ: дописать эксплуатационные заметки, взять фрагмент во внутренние материалы. Документ, за который заплатили, часто просто лежит в архиве.

3. Договорной взгляд: спецификация — это «результат работ»

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

То есть спор «Excel или Word» имеет смысл только после того, как стоит этот фундамент.

• Какие документы входят в результат работ: не «комплект документации», а перечень по именам документов
• В каком формате их получают: входит ли редактируемый оригинал (файл Word или Excel). Один PDF на сопровождении мешает
• Как принимают: что нужно проверить, чтобы принять. Как показывают различия в исправленной версии
• Авторские права и вторичное использование: может ли заказчик копировать и менять документ внутри компании. Можно ли передать документ, если сопровождение позже поручат другой компании

Если этого нет в договоре, какой бы удачный формат ни выбрали, спор сведётся к вопросу «входил ли этот документ в сдачу». Что стоит согласовать до заказа, см. также «Что стоит продумать, прежде чем заказывать разработку Windows-приложения».

4. Варианты формата сдачи: сравнение по критерию «работает ли это как результат работ»

Когда фундамент есть, выбирают формат. Оси оценки — те же, что в начале: насколько заказчику удобно читать / насколько легко ревьюить и принимать / как управлять различиями при изменении спецификации / насколько документ живёт на сопровождении.

Смысл оценочных знаков такой. Оцениваем, есть ли механизм в самом формате как в инструменте. То, что можно закрыть договорённостями о процессе, в оценку не входит.

Три клетки с △ — сразу с причиной.

• Управление различиями в Excel — △: нет механизма, который, как режим исправлений Word, показывает правки красным. Журнал версий значений ячеек и Spreadsheet Compare существуют, но часто требуют совместного редактирования, а текст внутри фигур и надписей не охватывают (раздел 2.1). На практике это закрывают правилом «прилагать перечень изменений».
• Устойчивость PDF на сопровождении — △: читать можно, но вести документ, сохраняя структуру, нельзя, поэтому рядом нужен редактируемый оригинал (раздел 4.3).
• Устойчивость Wiki на сопровождении — △: обновлять как раз удобнее всего, но останется ли документ после окончания договора, зависит от договора на инструмент и от настроек. Если заранее не решить, можно ли экспортировать, кому принадлежит пространство и как живут учётные записи, в момент окончания договора доступ к документам пропадает (раздел 4.5).

Дальше — по каждому варианту.

4.1 Word — первый выбор для текстовой спецификации

Документ, который «рассказывает текстом» — обзорная проектная документация, описание бизнес-процесса, — по природе своей для текстового редактора. В Word с самого начала есть то, что нужно сдаваемому документу.

• Стили заголовков и автоматическое оглавление: структура документа ясна, из оглавления можно перейти к нужному месту
• Режим исправлений (рецензирование): в исправленной версии видно красным, что изменилось. Ревью и приёмка становятся другими по смыслу
• Комментарии: замечания заказчика и ответы остаются в самом документе
• Сравнение документов: различия двух версий можно показать и позже

Заказчику не нужны ни особые инструменты, ни обучение, и то, что Word принимают как формат сдачи без оговорок, на практике тоже важно.

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

4.2 Excel вернуть к роли «настоящей таблицы»

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

• Одна строка — одна запись, один столбец — один атрибут. На одном листе — одна таблица
• Не собирать вёрстку объединением ячеек. Заголовки — одна строка сверху
• Не ломать структуру данных ради вида на печати (печатное оформление — отдельно)

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

4.3 PDF — формат, в котором фиксируют «согласованную версию»

То, что PDF нелегко править, — и минус, и плюс. Как оригинал спецификации он не годится, но как снимок версии, прошедшей приёмку, или версии, согласованной при изменении спецификации, подходит. Его не перепишут случайно, поэтому он работает как запись «на этот момент договорились так».

Строго говоря, PDF тоже можно собрать заново. Сила записи — не в самом формате PDF, а в том, что обе стороны хранят один и тот же файл. Поэтому это сочетают с отправкой по почте с сохранением следа отправки и с хранением в обеих средах. Если нужна ещё и доказательная сила при споре, вариант — электронная подпись или метка времени.

Второй принцип простой: PDF всегда идёт вместе с редактируемым оригиналом. Сдача только PDF сужает будущий выбор заказчика: использовать документ у себя, передать сопровождение другой компании.

4.4 Оригинал на Markdown + Git, сдача — сгенерированные Word / PDF

На стороне компании-разработчика в последние годы шире пишут спецификацию в Markdown и ведут её в том же Git-репозитории, что и исходный код. Видны построчные различия, документ ревьюят тем же механизмом, что и код, история изменений остаётся в журнале (для практики разработки этого достаточно; если нужна доказательная сила для аудита или спора, отдельно запрещают переписывать историю).

Git от заказчика требовать не нужно. Если оригинал ведут в Markdown, а сдаваемый файл — Word или PDF, сгенерированный преобразователем вроде Pandoc, заказчик по-прежнему просто получает Word/PDF. Эффективность ведения на стороне разработки и удобство чтения на стороне заказчика совмещаются.

Pandoc здесь — бесплатный инструмент взаимного преобразования форматов документов (открытый исходный код, запускается из командной строки). Он умеет переводить Markdown в Word (.docx), PDF, HTML и многие другие форматы. Если задать свой файл Word с логотипом и стилями заголовков как шаблон, сгенерированный Word можно подогнать под внутренний стандарт оформления. Ставят инструмент только у разработчика — заказчику новые инструменты не нужны. Это часто понимают неправильно, поэтому при предложении стоит сказать прямо.

Поток выглядит так.

［сторона разработчика］
  Спецификацию пишут в Markdown
        ↓
  Ведут в том же Git-репозитории, что и исходный код
    ・ видны построчные различия
    ・ документ ревьюят тем же механизмом, что и код
    ・ в истории остаётся, когда, кто и зачем менял
        ↓
  Преобразуют Pandoc (в качестве оформления задают свой шаблон Word)
        ↓
  Получаются Word / PDF
        ↓
─────────── сдача ───────────
        ↓
［сторона заказчика］
  Как и раньше, получает Word / PDF, читает и ревьюит
        ↓
  Запросы на правку возвращает комментариями (сгенерированный файл напрямую не правят)
        ↓
  Разработчик вносит правки в оригинальный Markdown, перегенерирует и сдаёт снова

Важно в договоре явно сказать, «что является оригиналом». Если заказчик правит сгенерированный Word напрямую, файл расходится с оригиналом. Нужна договорённость о процессе: как в конце схемы — запросы на правку принимать комментариями и вносить в оригинал.

4.5 Wiki и онлайн-инструменты — «живая спецификация», когда сопровождение идёт постоянно

Для системы с действующим договором сопровождения и частыми доработками сильный вариант — постоянно обновлять спецификацию в онлайн-инструменте вроде Notion или Confluence. Хорошо ищется, история изменений пишется сама, формат легче держать не как «сдали и забыли», а как «живой документ».

Но как результат работ нужно заранее решить, что останется, когда договор закончится: формат экспорта (можно ли выгрузить в Word или PDF), кому принадлежит пространство и кто платит, как устроены учётные записи для просмотра. Если оставить это размытым, появляется привязка к конкретному инструменту, и в момент окончания договора можно потерять доступ к документам.

5. Как вести переписку по изменению спецификации

Даже с хорошим форматом без правил процесса снова всплывёт «какая версия последняя». Сдача — не конец: спецификация меняется и в разработке, и на сопровождении. Базовая схема такая.

1. Вести один журнал управления изменениями: список, где в одной строке — номер изменения, дата, содержание, влияние (стоимость/сроки), кто согласовал. Для этого хватает обычной таблицы Excel. Сопоставьте его с процедурой управления изменениями модельного договора IPA (см. статью выше)
2. Гонять правки документа так, чтобы было видно, что изменилось: для Word включают режим исправлений и отправляют исправленную версию, заказчик смотрит в первую очередь красное. Если боитесь, что исправления где-то не включили, принимающая сторона сверит предыдущую согласованную версию функцией «Сравнить» в Word и найдёт пропуск. После согласования принимают исправления и фиксируют версию
3. Задать правило нумерации версий: версию приёмки назвать v1.0 и при каждом согласованном изменении поднимать до v1.1, v1.2. В имени файла не использовать «финал», «испр.», «(2)»
4. Согласованную версию фиксировать в PDF и хранить обеим сторонам: чтобы потом любой мог установить, по какой версии было согласие

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

6. Что заказчику проверить до договора

Для стороны, которая заказывает работу, чек-лист на этапе сметы и договора.

• Спецификации и проектная документация входят в перечень результата работ по именам документов (а не как размытый «комплект документации»)?
• Получите ли редактируемый оригинал (файл Word/Excel и т. п.)? Не сводится ли всё к одному PDF?
• Исправленную версию дают в виде, из которого видно, что изменилось (режим исправлений, перечень изменений)?
• В договор сопровождения входит обновление документов при доработках? Если нет — готовы ли вы к тому, что документы будут расходиться с системой?
• Как устроены авторские права и вторичное использование документа. Можно ли передать документ, если сопровождение позже поручат другой компании?
• Зафиксирована ли процедура изменения спецификации (журнал управления изменениями, как оставляют согласие)?

С стороны исполнителя этот же список сразу годится, чтобы собрать смету. Какой документ писать и с какой детализацией — это трудозатраты и деньги. Взяв заказ с размытым составом результата работ, ближе к сдаче получите расхождение: «мы считали, что этот документ тоже входит». Заранее согласовать перечень и формат документов — защита обеих сторон.

Итог

Кратко о спецификации, которую сдают в заказной разработке.

• Формат сдаваемой спецификации выбирают с точки зрения приёмки, изменения спецификации и сопровождения. Не только по критерию «удобно ли писать во время разработки»
• Суть проблем Excel «в клеточку» — выхолащивание приёмки, потому что не видно различий, потеря записи о согласии, расхождение с реализацией из‑за высокой стоимости обновления
• Вывод — не «полный отказ от Excel», а возврат к формату по назначению. Текст — Word (стили + режим исправлений), таблицы — обычные таблицы Excel, фиксация согласия — PDF
• Если оригинал на стороне разработки вести в Markdown+Git, а сдавать сгенерированные Word/PDF, преимущества обеих сторон совмещаются
• Раньше формата в договоре решают перечень результата работ, сдачу редактируемого оригинала и авторские права. Согласовать правила процесса важнее, чем инструмент

О чтении и записи Excel из программы (вывод отчётов) — в статье «Как сделать вывод отчётов Excel — COM/Open XML/шаблоны», о сборке договора — в разборе «Модельных сделок и договоров» IPA. Имеет смысл читать вместе.

Справочные ссылки

• IPA «Модельные сделки и договоры для информационных систем» ─ упомянутый в главе 3 шаблон договора, в котором задают перечень сдаваемых материалов, способ и срок приёмки, процедуру управления изменениями. Доступен бесплатно и заказчику, и исполнителю
• IPA «Модельные сделки и договоры для информационных систем», вторая редакция (пересмотр с учётом реформы Гражданского кодекса) ─ действующая вторая редакция и пояснения к ней
• Pandoc ─ официальный сайт преобразователя документов из раздела 4.4. Список форматов и работа с шаблоном Word
• IPA «Градация нефункциональных требований» ─ чтобы не забыть нефункциональные требования в спецификации. Разбор — в отдельной статье

Тем, кто рассматривает заказную разработку или сопровождение

В KomuraSoft LLC, принимая заказную разработку Windows-приложений для бизнеса, мы с самого начала согласуем с заказчиком состав, формат и правила обновления документации результата работ по логике этой статьи. На доработке существующего ПО берём и обследование состояния «спецификация вроде есть, но неизвестно, совпадает ли с системой». Пишите, в том числе если нужно навести порядок в спецификациях или пересмотреть формат сдачи.

Похожие статьи

Недавние статьи с теми же тегами помогут подробнее изучить близкие темы.

Связанные темы

Эти страницы показывают тему статьи в более широком контексте услуг и решений.

Услуги по этой теме

Статья напрямую связана со следующими услугами.

Частые вопросы

Вопросы, которые часто возникают при консультациях по теме статьи.

Заказчик задал шаблон Excel «в клеточку». Придётся следовать?

Следовать указанному формату сдачи — обязанность исполнителя, но стоит уточнить, зачем это требование. Если цель — внутренний стандарт документов или подготовка к аудиту, иногда можно предложить тот же состав в шаблоне Word. Нередко шаблон просто тянется по привычке. Даже если формат не сменить, многие проблемы «не видно, что изменилось» снимаются процессом: к исправленной версии прилагать перечень изменений, согласованную версию фиксировать в PDF.

Спецификацию сдали только в PDF. Это проблема?

В момент сдачи это не выглядит проблемой: документ читается. Трудности начинаются на сопровождении и доработках. PDF править специализированными инструментами можно, но вести его дальше, сохраняя структуру, как в Word или Excel, нереально. С каждым изменением спецификации документ всё сильнее расходится с реализацией. Если позже сопровождение передадут другой компании, без редактируемого оригинала документ трудно передать. Надёжнее в договоре прямо указать условие результата работ: «сдача включает редактируемый формат (оригинал Word или Excel)». Если уже получили только PDF, попросите компанию-разработчика отдать оригинал.

Насколько подробно должна быть написана спецификация?

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

Кто отвечает за обновление спецификации после сдачи?

Зависит от договора. Если в договор сопровождения входит «обновление проектной документации при доработках», это работа исполнителя. Если не входит, обновление либо заказывают отдельно на каждую доработку, либо принимают, что документ будет расходиться с системой. Конфликты чаще всего бывают, когда этот пункт не зафиксировали, и обе стороны думают: «разумеется, документ обновляется». При заключении договора сопровождения лучше перечислить по именам, какие документы входят в сопровождение.

Об авторе

Страница с профилем автора статьи.

Го Комура

Представитель KomuraSoft LLC

Специализируется на разработке программного обеспечения для Windows, техническом консалтинге и расследовании сбоев, особенно в проектах с унаследованными системами и трудно воспроизводимыми ошибками.