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

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

«Собрались заказать доработку, а поставленное ТЗ в Excel оказалось совершенно не похоже на нынешние экраны».

«От компании-разработчика пришло ТЗ в виде Excel-«миллиметровки» — это вообще нормально?»

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

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

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

Сначала соберём ключевые моменты.

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

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

Далее по порядку объясняем, почему именно так.

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. Варианты формата поставки — сравнение по критерию «работает ли это как результат работы»

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

Дополним по каждому пункту.

4.1 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, как и раньше. Это позволяет совместить эффективность управления на стороне разработки с удобством чтения на стороне заказчика.

Нюанс в том, чтобы явно закрепить в договоре, «что именно является оригиналом». Если заказчик напрямую правит сгенерированный файл 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?
• Будет ли исправленная версия при получении представлена в форме, показывающей, что изменилось (отслеживание изменений, список изменённых разделов)?
• Входит ли в объём договора на сопровождение обновление документов при доработках? Если нет — устраивает ли вас, что документы будут постепенно расходиться с реальностью?
• Как обращаются с авторским правом и вторичным использованием документа. Можно ли будет передать документ, если в будущем сопровождение поручат другой компании?
• Определена ли процедура изменения спецификации (реестр управления изменениями, способ фиксации согласования)?

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

7. Часто задаваемые вопросы

В1. Заказчик указал шаблон Excel-«миллиметровки». Обязательно ли ему следовать?

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

В2. ТЗ получили только в формате PDF. Это проблема?

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

В3. Насколько подробным должно быть ТЗ?

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

В4. Кто отвечает за обновление ТЗ после поставки?

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

Итог

Соберём ключевые тезисы этой статьи о спецификациях, поставляемых в контрактной разработке.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ТЗ получили только в формате PDF. Это проблема?

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

Насколько подробным должно быть ТЗ?

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

Кто отвечает за обновление ТЗ после поставки?

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

Об авторе

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

Го Комура

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

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