Как (инструмент ,методика) обеспечить прослеживаемость от требований через ТЗ до кода вверх и вниз?

Question

[Ndochp]

Ситуация: есть несколько логически связанных уровней документации + код.
Например:
1. Аналитическая записка (АЗ) с описанием что и зачем должна делать программа, (порождает ТЗ (что писать программисту), инструкцию пользователя.)
2. Техническое задание (ТЗ) порождает код,
3. Инструкция пользователя по системе (может быть основой для курсов операторов/упрощенных инструкция по конкретным операциям)
5. код
6. Контрольный пример (рождается на основе инструкции и АЗ)
Каждый документ страниц на 50-200, ну и код не новый, а унаследованный, так что его вообще немеряно.

Пусть на проверке контрольного примера мы наткнулись на проблему. Есть какая-то система обработки/хранения документации, работающия методика по организации документации, которая позволит выйти на нужные участки инструкции/аналитической записки/тех задания, которые должны быть проанализированы, если мы знаем место сбоя в контрольном примере?
Желательно конечно все под контролем версий с возможностью помечать "согласованные" (когда документация по нашему предположению непротиворечива) версии, и откатываться на них, если надо.

Answer 1

[Эдуард Тибет]

1. Есть системы работы с требованиями. Специально под это заточенные. Как правило, под винду. Но они НЕ являются plain text форматами. Например, вот такой подход: https://en.wikipedia.org/wiki/Software_configurati... (и, в частности https://en.wikipedia.org/wiki/Rational_ClearCase_UCM )

2. Можно использовать single sourcing technical documentation (DocBook, DITA) c построением всей схемы работы. Вам потребуется: человек, который все это сделает и бюджет под это дело.

Сразу скажу, что в обоих случаях удовольствие недешевое. И не факт, что п.1 будет дешевле п.2

P.S. Предполагаю, что все-таки под контрольными примерами понимается test case.

Comments

[Ndochp]

Контрольный пример в моем случае (КП) это ручные приемочные тесты для крупной фичи (документ ворд с картинками). Автор КП - разработчик со скриншотами описывает типовую операцию от начала до конца (как правило цепочка из 5-7 документов + отчет с результатами). Используются заказчиком двояко - как приемочный тест при сдаче работы и как инструкция "в картинках" для операторов, которым сложно разбираться с пользовательской документацией.

[Эдуард Тибет]

Судя по терминологии, вы работаете с госзаказчиками?

[Ndochp]

Близко, налаживаем 1С в крупной конторе, которая работает с госзаказчиком.
Но в ситуации скорее наложились проблемы при разработке (самая актуальная "документация" это почта, потом код, потом инструкции пользователей, а документы верхнего уровня отражают видение на 3 года назад) с курсом Introduction to Systems Engineering на курсере, где много говорится про важность отслеживания требований в обе стороны, но (по крайней мере пока) ничего про инструменты.

[Ndochp]

Эдуард Тибет: Эдуард, насколько я понимаю путь 2 это не совсем то. Если только не считать АЗ, ТЗ и инструкцию одним документом, написанным на разных языках. Вроде при этом подходе мы пишем один раз и по разному отображаем на разные выходные форматы. А тут текст будет сильно разным - в разных документах мы скорее не копируем куски разными словами, а ссылаемся вверх по иерархии, обосновывая решение. В итоге связь между кусками документов не один к одному, а скорее многие ко многим.

По первому пункту погряз в перекрестных ссылках, а IBM кажется бесплатно не пощупать.

[Эдуард Тибет]

Пункт 2 включает в себя и т.н. reuse content - это один из основных преимуществ single sourcing (технологически включение осуществляется по разному в DocBook и DITA, но это не суть). Т.е. single sourcing - это не столько вывод представления в разных форматах, сколько использование одного и того же контента в разных ситуациях и документах. Приведу грубый пример: вам достаточно будет одного документа, в котором будет фраза "Система [должна обеспечивать]/[обеспечивает] вывод графика в формате PNG". Если вы сделаете выборку по одному тегу - получаете ТЗ, а по другому - руководство пользователя в разделе "Основные функции".

Answer 2

[Vov Vov]

Как ни парадоксально это звучит, но улучшение прослеживаемости требований не приведёт к улучшению качества. - это скажем так, моё утверждение :)

Сама концепция написания АЗ и ТЗ утратила актуальность. Процессы согласования, утверждения и планирования отнимают слишком много бесценного и дорого времени. Мой рецепт не претендует на универсальность, но для моих задач он работал и работает прекрасно. Метод был уже описан западными авторами, но, как мы все понимаем, методология в чистом виде нигде не применяется, а всегда добавляются свои специфические примеси или наоборот, что-то убирается. Данный метод можно назвать "Быстрое прототипирование", предпосылками для такого метода является, то что люди в сотни раз быстрее воспринимают визуальные (графические) концепции, чем текстовые описания, таким образом, если делать быстрые графические прототипы (1-2 дня) и запускать цепочку согласования, то обратную связь можно получить за те же 1-2 дня, далее 1 день на агрегацию и подготовку короткого описания 1-3 страницы, вместо 15 как раньше. После согласования, этап подготовки спецификации для разработчиков (1 день).
Также привествуются создание универсальных моделей прототипов, например, которые описывают некоторые стандартные особенности без привязки в функциональности, таким образом на этапе тестирования и подготовки тест-кейсов/тест-планов по конкретной функциональности учитывают "стандартные" поведенческие особенности, что приводит к общему улучшению качества.
Ещё очень эффективным инструментом лечения всяких болячек в софте является следование практикам ISO 9001 в частности сбор обратной связи с клиентов, проведение советов по качеству, надзор внутри организации за процессами (на сколько качественно они выполняются и т.п.). Это глобальная тема, но при желании можно её осилить.

P.S. Для создания быстрых прототипов можно использовать разный софт, но мне больше все полюбился Balsamiq. Для описания требований есть ещё Rational RequisitePro (www.caseclub.ru/articles/requisite.html), более глобальный инструмент с моделированием процессов Aris, но я считаю что это уже олдскул и надо решать эти задачи вышеописанным методом.
P.S. Чтобы было понимание всё о чём я писал работало на численности разработчиков от 15 до 120, а то мало ли у Вас там тысячи :)

Comments

[Ndochp]

Боюсь, что у нас разные области применения софта. У вас похоже важен внешний вид/удобство использования, у меня - связность движений в базе. В итоге фаза прототипа остается на уровне экселя, а не кода. До удобства оператора дело может и не дойти. А вот когда через пару лет возникает вопрос, а "зачем мы делаем такие движения", то прочитать это из АЗ проще, чем из инструкции, ТЗ и тем более кода. Так как АЗ не обременено деталями реализации и именами таблиц БД, зато там есть ссылки на законодательство. И если документ по ссылке устарел, то пора менять реализацию. А если нет, то надо понять - у нас ошибка в реализации, или пользователь со стороны заказчика хочет странного и его надо слать к методологам.

[Эдуард Тибет]

Немного встряну в разговор... У Владимир Сидоров - типичный Agile со всеми вытекающими. А у Ndochp - типичный водопад (или "хочется, чтобы бы водопад"). Два разных подхода - и что конкретно нужно в вашей ситуации - решать только вам.

[Ndochp]

Эдуард Тибет: Эдуард, не столько хочется водопада, сколько документации, соответствующей программе. Разрабатывать я готов в любом порядке :)

[Эдуард Тибет]

Мой комментарий был в том ключе, что у вас обоих разные подходы. И, судя по логике, у вас используется именно водопад (м.б. это требование заказчика, не знаю). А что вы в итоге выберете - это уже вам решать.