Почему ИТ-проекты встают на документах. Взгляд подрядчика

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

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

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

Вторая оговорка важнее. Данный материал не является попыткой высказать претензию к заказчикам. Напротив, во всех описанных случаях заказчик действовал разумно, а сложности возникали из-за того, как устроен сам процесс, — и мы в этом процессе участвуем на равных. Свои ошибки я тоже привожу, их было достаточно. Итак, предлагаю приступить!

Состав документации не зафиксировали на старте

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

Хотел бы раскрыть эту боль на кейсе, когда заказчик попросил нас сделать два нетиповых документа — «Описание бизнес-процессов системы» и «Описание пользовательских сценариев». Документы полезные, и желание заказчика их получить я понимаю: ГОСТ дает комплектность, но не дает наглядной картины, как система работает с точки зрения предметной логики.

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

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

В итоге «описание процессов» разрослось до состава, которого никто не планировал: используемые в процессе справочники, таблицы базы данных, макеты доступных пользователю дашбордов, шаблоны формируемых документов — хотя они и так сдаются в составе технического проекта, — описание методов интеграционного взаимодействия с sequence-диаграммами. И так далее.

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

Формат испытаний поменяли за две недели до испытаний

Испытания — краеугольное мероприятие приемки. Большинство контрактов, по которым мы работаем, предписывают проводить испытания в три этапа по ГОСТ Р 59792: предварительные испытания, опытная эксплуатация и приемочные испытания. Каждый этап идет по своей программе и методике испытаний (ПМИ). Классическая ПМИ — это шаги проверок, привязанные к функциональным требованиям.

В одном из проектов заказчик захотел иначе: предварительные испытания по сценариям с разбором пользовательских кейсов. Логика в этом есть, но раньше такой подход практиковался на уровне опытной эксплуатации. Здесь же требование предъявили к предварительным испытаниям.

Сформировалось требование относительно поздно. К тому моменту ПМИ полтора месяца проходило согласование и уже получило одобрение экспертной организации заказчика. До крайней доступной точки для проведения испытаний оставалось две недели.

Мы не стали выбирать между двумя подходами. Классические методики сохранили как обязательный элемент, этого требует ГОСТ Р 59792. Сценарии сделали надстройкой сверху. Чтобы конструкция не развалилась, понадобилось обеспечить трассируемость: доказать, что каждое функциональное требование по-прежнему проверяется, просто теперь еще и внутри сценария.

На практике это дополнительное приложение к ПМИ на 40 страниц и таблица сопоставления — матрица из 16 сценариев на 63 функциональных требования. Плюс переработка тест-кейсов и подготовка данных на испытательном стенде под новые сценарии. Сложность была даже не в объеме страниц: нужно было верно определить и задокументировать больше тысячи логических связей. За две (!) недели.

Читайте также

ИИ-бум столкнулся с долговой реальностью

ИИ-компании заключают контракты на сотни миллиардов долларов, но инвесторы уже сомневаются, что эти деньги удастся заработать. Долги операторов дата-центров растут, облигации дешевеют, а производители чипов сами финансируют своих покупателей. Не окажется ли ИИ-бум построенным на заемных деньгах?

Спойлер: ПМИ согласовали, испытания прошли без замечаний, и даже успели сделать две итерации правок с заказчиком. Удалось все ровно по одной причине: мы ведем документы в модели docs-as-code. Документ для нас — это строки кода, описательные сущности живут переменными в базе данных, а представлением управляет язык шаблонизации. Пересобрать сорок страниц приложения и перестроить матрицу в такой модели — работа на недели, и в отведенные две мы уложились. В обычном формате, где документ существует как файл в Word, это минимум месяц ручной работы без гарантии отсутствия ошибок.

Поэтому, если кейс в чем-то откликается, и вы еще живете в парадигме «документы в Word», рекомендую посмотреть в сторону docs-as-code.

Cобственная ошибка

Мы в своих первых проектах не прописывали детально состав и объем тестовых данных, на которых проводятся испытания. На фоне методик и матриц трассируемости это выглядит мелочью — ровно до того момента, когда формат испытаний меняется. Тогда выясняется, что данные под новые сценарии надо готовить почти с нуля, а сколько их надо и какие они, нигде не написано.

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

Сейчас состав и объем тестовых данных мы фиксируем вместе с ПМИ и привязываем к шагам проверок и тестовым сценариям. Взяли это для себя как обязательный элемент ПМИ и еще один способ минимизировать риски неприемки.

Документацию пишут в последнюю ночь до сдачи

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

Раньше это выглядело так. Сначала техписатель работает по макетам. Потом появляется альфа-сборка — работающей системы еще нет, но уже есть на чем строить каркас документа. Потом начинается итерационная петля правок, потому что интерфейс меняется, а описанное перестает соответствовать. И весь этот цикл приходится на финал проекта, когда времени уже нет.

После ряда таких авральных кейсов мы нашли способ сдвинуть документирование влево. Прототипирование теперь не заканчивается макетами в инструменте дизайна: мы собираем полноценные HTML-прототипы, которые имитируют пользовательский интерфейс — юзабилити, состояния экранов, статусы, процессную логику. Без бэкенда, но с хранением локальных данных через localStorage, так что прототип ведет себя как система. Собирать такие прототипы стало реально быстро с языковыми моделями: раньше это была отдельная разработка, теперь работа аналитика с моделью. Даже набор мок-данных и тест-кейсов в ряде случаев удается держать отдельными JSON-файлами для импорта в прототип.

За два месяца до испытаний у технических писателей и тестировщиков уже есть на чем работать. ПМИ можно написать и тут же прогнать по прототипу. Руководство пользователя пишется по условно живым экранам.

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

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

***

Что общего у всех случаев?. Каждый раз мы платили временем за то, что не было проговорено на старте. Не заказчиком, не нами — просто не проговорено, потому что на старте всем кажется, что это очевидно и обсуждать нечего. Но я бы не уходил в мысль, что можно все заранее проговорить, по крайней мере на масштабных проектах, а скорее, что для подрядчика ключевым фактором становится инструментарий быстрой адаптации к проявлению непредвиденных последствий. В части подготовки документов нас очень выручил переезд на docs-as-code и внедрение практики HTML-прототипов.