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

Как обычно выглядят наши «митинги»?

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

Тем временем аналитик:

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

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

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

Определение из стандарта по системной инженерии.

Под это определение попадают многие, если не все рукотворные объекты, в том числе и документация. C точки зрения теории решения изобретательских задач (ТРИЗ):

Идеальная система — это такая система, которой нет, а функция которой выполняется.

Близкое к идеальному транспортное средство было, кстати, у пушкинской Бабы-Яги: ее ступа двигалась “сама собой”. Но сама ступа-то все-таки была, в нее надо было залезать, из нее надо было вылезать, поэтому это транспортное средство не стопроцентно идеальное.

Первые компьютеры занимали в длину десятки метров, а первые сотовые телефоны весили существенно больше нынешних. Технические решения стремятся к компактности, идеальности. Достижение большего результата с меньшей, более простой конструкцией. На замену сложных языков программирования, таких как С++, Delphi, приходят более простые, например Go. Это не вполне интуитивно, кажется, что техника и окружающий мир вместе с техникой становятся более сложными. Эта сложность связана с наращиваем функциональности (например автопилот, и другие электронные системы в машинах), а не с усложнением инженерных решений как таковых.

В ТРИЗ выделяют два вида идеализации систем:

Масса (М), габариты (Г), энергоемкость (Э) стремятся к нулю, а количество выполняемых функций остается неизменным.
Количество функций увеличивается, а масса, габариты, энергоемкость остаются неизменными.

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

Об этом же, например говорит, подход JBGE (just barely good enough). На диаграмме отображается степень проработанности артефактов описания.

Но как определить идеальный уровень? Естественно, всё зависит от конфигурации и зрелости команды. Мой опыт подсказывает, что основная сложность как правило сосредоточена в предметной области, — и отсутствие единого понимания, на уровне отдельной сущности или на уровне отдельного атрибута приводит к катастрофическим последствиям. О важности единого языка многое сказано в DDD (Предметно-ориентированном проектировании), и безотносительно подхода, согласуется со здравым смыслом.

Но почему-то вместо, того, чтобы в требованиях на позицию аналитика указывать DDD или спрашивать на собеседовании в чём различие между определением, понятием, символом — мы слышим вопросы по типу «в чём разница между put и patch» и т. д. И на основании этих знаний определяем уровень, создаём будущие ожидания, и то к каким знаниям стремиться. В то время, как формирование категорий и понятий самый мощный инструмент работы аналитика. Аналитик ни столько описанием устройства системы занимается, — сколько формированием единого языка. На одном из моих первых проектов, ко мне подошёл руководитель, и сказал: «Андрей, составь список терминов и нарисуй логическую модель данных, и если у тебя на ней всё "сошлось", то можешь больше вообще ничем не заниматься. Оставь немного работы для программистов». Теперь, спустя некоторое время, я понимаю, что по большому счёту он был прав. Качественно проработанная логическая модель данных, список терминов, ключевых сценариев и бизнес-правил — это тот минимум, который должен поддерживаться в безупречном виде.

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

Пользователь должен иметь возможность найти нужную информацию о системе не более чем за пять минут (удобство использования).
Пользователь должен иметь возможность внести изменения в описываемую функцию не более чем за пятнадцать минут, не нарушив согласованности документа (изменяемость, поддерживаемость).

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

В моём представлении идеальная документация умещается на нескольких листах А4 и отвечает на все критически-важные вопросы проекта. Этого сложно достичь, — что не мешает нам к этому стремиться.

НФТ к документации: Своя игра