Каким образом вы отображаете изменения требований в документации?




Главная   Форумы   Шаблоны и вопросы по документации как одному из результатов работы бизнес-аналитика.   Каким образом вы отображаете изменения требований в документации?

В теме 28 ответов, и 5 участников, последнее обновление сделано пользователем Аватар (ekaterina) ekaterina 3 г, 11 мес. назад.

Показано 15 ответов - от 1 до 15 (всего 29)
  • Автор
    Сообщения
  • 06.10.2013 в 22:21 # 16481
    Аватар (Alena)
    Alena
    Подписчик
    Ситуация следующая: произведен сбор требований, они зафиксированы в документе (наподобие SRS), документ подписан заказчиком. Но, как известно, требованиям свойственно изменяться, и после подписания документа возникает необходимость фиксирования этих изменений для внутреннего использования. Иначе возникает ситуация, когда документ перестает отражать реальную ситуацию и становится просто бесполезным. Работа по водопадной модели.

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

    Может быть у кого-то есть опыт использования других способов отражения изменений в проектной документации? Или рекомендации по описанному выше способу? Заранее благодарна за помощь!

    Поделиться:

    Цитировать

    08.10.2013 в 00:46 # 16482
    Привет.

    1) Как минимум, версионность. Baselines требований должны быть, во-первых, зафиксированы, а во-вторых, сохранены. Например, в вашей системе контроля версий. Любое осмысленное изменение требований — это отдельная версия документа, сохраненная в истории VCS с возможностью отката на нее.

    2) История изменений (то, что вы написали) с указанием источника, сути, даты и автора изменений. Трассировка на другие артефакты — письма, issue, work item и т.д.

    3) Цветовая или иная схема для отличия от предыдущей версии. Вариант раз — ручное цветовое оформление. Вариант два — режим правки в MS Word.

    Вот это все желательно бы делать совместно.

    Альтернативы:

    1) Онлайн wiki-based система с поддержкой истории (например, Confluence) — такая система сама покажет различия между любыми версиями. Применимо практически для любых проектов, но в основном для менее формализованных требований (Agile и иже с ним).

    2) Requirements management tool — практически во всех подобных инструментах ключевой фичей является хранение истории изменения требований и поддержка baselines.  Окупает себя с лихвой, в основном, на больших проектах/больших командах.

    Я не знаю, понятно ли все описанное выше, поэтому, если нужны пояснения, дайте знать.

    Поделиться:

    Благодарностей: 1   Цитировать

    08.10.2013 в 10:30 # 16483
    Аватар (Alena)
    Alena
    Подписчик
    Добрый день!

    Герман, большое спасибо за ответ! Все понятно написано.

    1) Версионность ведется, с этим проблем нет. Предыдущие версии блокируются от изменений. Подписанная версия документа переводится в PDF.

    2) Вчера мне посоветовали использовать перекрестные ссылки в MS Word (документы в нем создаются) для более удобного внесения изменений. А также — Лист изменений (дата изменения, автор, исполнитель, суть изменения) и раздел «Открытые вопросы» (дата, инициатор, содержание ).

    Трассировка на другие артефакты — письма, issue, work item и т.д.

    Здесь вы имеете ввиду словесное описание артефактов в листе изменений?

    3) По поводу выделения изменений другим цветом и использования режима рецензирования в MS Word мнения расходятся. Мне, например, больше нравится идея выделять изменения другим цветом, чем использовать режим рецензирования, т.к. у каждого он отображает изменения по-своему. Кто-то вообще против и того и другого.

    Что касается альтернативных инструментов работы с требованиями, это пока для нас не актуально.

     

    Поделиться:

    Цитировать

    08.10.2013 в 13:29 # 16484
    Алена, добрый день!

    1) А как перекрестные ссылки помогут для отслеживания изменений? Вообще, это, конечно, штука удобная — например, когда нужно ссылаться на макеты или другие объекты, которые могут перенумероваться.

    2) Трассировка на другие артефакты — письма, issue, work item и т.д. Да, я имел в виду ссылку на эти вещи. Словесную или, например, гиперссылку — это уже как инструментарий позволяет. Суть в том, что вы должны иметь возможность уникально идентифицировать и найти то, что послужило источником изменений (например, точный номер issue от клиента в баг-трекинг системе).

    А если не секрет, почему, к примеру, Вики для вас не актуально?:)

    Поделиться:

    Цитировать

    08.10.2013 в 16:33 # 16485
    Аватар (Alena)
    Alena
    Подписчик
    1) Вы совершенно верно заметили — перекрестные ссылки не помогут отследить изменения. Я планирую их использовать в листе изменений для того, чтобы можно было быстро перейти к измененному фрагменту текста. Иначе придется искать по документу, что имелось ввиду под кратким описанием изменения. Мне кажется, что это не очень удобно.

    2) Я так понимаю, что это предполагает наличие отдельного столбца в листе изменений, например «Основание для внесения изменения» или «Источник»?

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

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

     

    Поделиться:

    Цитировать

    08.10.2013 в 17:19 # 16486
    1) Так для этих целей вам пригодятся обычные ссылки. Перекрестные то зачем?:) Вообще да, ссылки, естественно, рулят.

    2) Ну это как вы решите. Источник однозначно где-то должен быть описан (отдельный столбец или в столбце с базовым описанием — неважно). Без источника вы просто не определите впоследствии, почему же кто-то влез и поковырялся в документе.

    Поделиться:

    Цитировать

    08.10.2013 в 17:56 # 16487
    Аватар (Alena)
    Alena
    Подписчик
    1) Ну все, я запуталась со ссылками :) А обычные ссылки (что, кстати, вы имеете ввиду под обычными) будут обновляться? Я планирую в листе изменений вставить столбец «№ страницы», где будут ссылки (уже не знаю, какой разновидности) на изменения. При нажатии на ссылку осуществляется переход к измененному фрагменту текста (сначала этот фрагмент выделяется и по нему создается закладка, на которую затем в листе изменений делается перекрестная ссылка). Если фрагмент текста куда-то переместился, то я могу просто обновить перекрестную ссылку с номером страницы  в листе изменений.

    А вы каким-то образом выделяете в тексте измененные требования или такой необходимости нет?

    2) Эту рекомендацию я учту, спасибо!

     

     

    Поделиться:

    Цитировать

    08.10.2013 в 18:09 # 16488
    Аватар (Alena)
    Alena
    Подписчик
    Вот как я примерно это представляю (см. вложение).
    Вложения:

    Вы должны войти, чтобы смотреть прикрепленные файлы.

    Поделиться:

    Цитировать

    08.10.2013 в 19:36 # 16490
    А, понял. Да, если вы так решили ссылаться на изменения, то да, вы правы, нужны перекрестные ссылки. Вопрос только, эффективна ли такая ссылка (номер страницы). Как альтернативу, могу предложить нечто в таком духе:

    08/10/2013   Иван Петров  Основание: Письмо от Вани Сидорова «Нужна новая фича» от 07/10/2013  Краткое описание: Добавлена фича…. обновлены бизнес-правила… и т.п.  Измененное содержимое: БП-01; Глава «Название новой клевой фичи»; Модель ВИ для проекта

     

    «А вы каким-то образом выделяете в тексте измененные требования или такой необходимости нет?» Да, цветовой схемой (удаленный контент — еще и зачеркиваем) вручную.

    Поделиться:

    Цитировать

    08.10.2013 в 21:08 # 16491
    Аватар (Alena)
    Alena
    Подписчик
    «Вопрос только, эффективна ли такая ссылка (номер страницы).»

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

    Для меня скорее возник вопрос целесообразности таких ссылок в связи с увеличением общей трудоемкости внесения изменений в документ:

    добавить пункт в лист изменений;
    добавить изменение в текст;
    сделать закладку на изменение в тексте (меню Вставка, кнопка Закладка в MS Word);
    сделать «кликабельную» ссылку в листе изменений для быстрого перехода к изменению (меню Вставка, кнопка Перекрестная ссылка в MS Word).

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

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

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

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

     »Как альтернативу, могу предложить нечто в таком духе:

    08/10/2013   Иван Петров  Основание: Письмо от Вани Сидорова «Нужна новая фича» от 07/10/2013  Краткое описание: Добавлена фича…. обновлены бизнес-правила… и т.п.  Измененное содержимое: БП-01; Глава «Название новой клевой фичи»; Модель ВИ для проекта»

    А если потом изменили название главы/раздела? Как тогда быстро перейти к  изменению в документе? В предлагаемом способе «Измененное содержимое» — это словесное описание?

    «Да, цветовой схемой (удаленный контент — еще и зачеркиваем) вручную.»

    А почему не используете режим рецензирования в MS Word? Меня некоторые убеждают, что это более удобный вариант, чем выделение другим цветом. Но я с этим не могу согласиться, поэтому было бы интересно услышать ваши аргументы.

    Если честно, первый раз в жизни написала на форум, т.к. не нашла информации в интернете.  Или я плохо искала, или здесь просится статья на  analyst.by :)

     

    Поделиться:

    Цитировать

    08.10.2013 в 21:44 # 16492
    Да-да, статье велкам:).

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

    «Получается достаточно долгий процесс. Не уверена, что коллеги поддержат такой способ работы с изменениями :)». Ну, если наловчиться… А еще и активно пользоваться горячими клавишами… Но да, вот он такой, этот процесс — мы делаем то же самое.

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

     

    «А если потом изменили название главы/раздела? Как тогда быстро перейти к  изменению в документе? В предлагаемом способе «Измененное содержимое» — это словесное описание?» Где-то у нас miscommunication, и я полагаю в целях и задачах спецификации:). В нашем типичном процессе (вариации не рассматриваю) изменение главы/раздела (например) — это уже очередная, новая версия документа. В версии документа, которая остается в истории системы контроля версий, глава/раздел/требование, на которое ссылается запись в Истории изменений, будет на месте (то бишь, цель достигнута — разработчик, заказчик или кто-либо иной сможет быстро перейти из Истории изменений в нужное место по ссылке). Если через N версий название/местоположение закладки изменится (и ссылка в Истории изменений станет неактуальной), то, собственно, ну и пусть. На тот момент эта запись свою роль сыграла и в том baseline документа ссылка красиво работает. Если же у вас цель в том, чтобы ссылка в Истории изменений всегда были рабочими, то это вроде как недостижимо, ибо в очередной итерации вы можете вообще выкосить половину документа за ненадобностью (бывает и такое). Интересно услышать ваши аргументы, потому что вроде как тут специфика вашего процесса меняет все в корне.

    Измененное содержание — это ссылки. Текст + hyperlinks (не перекрестные ссылки, так как их актуальность в последующих версиях значения не имеет).

    «А почему не используете режим рецензирования в MS Word? Меня некоторые убеждают, что это более удобный вариант, чем выделение другим цветом. Но я с этим не могу согласиться, поэтому было бы интересно услышать ваши аргументы.»

    Мы периодически проводим т.н. взаимный peer review документов (верификация требований), и там используется режим правки. Чтобы это не путалось с версионными изменениями,  мы делаем цветовую схему вручную. Плюс, как по мне, так режим правки какой-то неэстетичный:) и отдавать это конечным потребителям в таком виде — как-то не есть имхо хорошо.

    Поделиться:

    Цитировать

    08.10.2013 в 22:41 # 16493
    Аватар (Alena)
    Alena
    Подписчик
    « Хм, а в чем роль спецификации требований у вас на проекте? Команда пользуется сим документом при разработке и тестировании? Если да, то как бы… ну точно не после приемки. Роль спецификации в конце проекта, конечно, все еще важна, но ведь не это ее основное предназначение. Хотя я не знаю специфики вашего проекта.»

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

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

    «Если через N версий название/местоположение закладки изменится (и ссылка в Истории изменений станет неактуальной), то, собственно, ну и пусть. На тот момент эта запись свою роль сыграла и в том baseline документа ссылка красиво работает. Если же у вас цель в том, чтобы ссылка в Истории изменений всегда были рабочими, то это вроде как недостижимо, ибо в очередной итерации вы можете вообще выкосить половину документа за ненадобностью (бывает и такое). Интересно услышать ваши аргументы, потому что вроде как тут специфика вашего процесса меняет все в корне.»

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

    «Плюс, как по мне, так режим правки какой-то неэстетичный:) и отдавать это конечным потребителям в таком виде — как-то не есть имхо хорошо.»

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

     

    Поделиться:

    Цитировать

    08.10.2013 в 23:56 # 16494
    «Вы при постановке задач разработчикам ссылаетесь на конкретные пункты спецификации? Как это вообще происходит?» Ну вариантов вообще много, но да — разработчикам дается спецификация, для них и для остальной команды — это основной документ, который является инструкцией для разработки, руководством для тестирования и т.п. На страницы мы не ссылаемся, но тут уже смотря, какая задача разработчику поступила, какова структура команды и т.д. Если разработчик полностью занимается разработкой фичи, UC, US, то там все понятно — читай весь раздел N. Если баг исправляет — сам найдет, где посмотреть (если документ грамотно составлен), если часть функционала разрабатывает — тим лид/ментор покажет и т.д. Но да, вы правы — процесс нужно некий выстроить, чтобы разработчик понимал, какой частью документа ему руководствоваться.

    «Классическая водопадная модель не предполагает итераций.»  Так она и изменений не предполагает:). Зачем тогда вам версионность и изменения в требованиях?

    «И я же предполагаю наличие только одной версии с историей изменений. По идее, конечно, может быть и такая ситуация «вы можете вообще выкосить половину документа за ненадобностью». Но это совсем плохой вариант развития событий для водопадной методики, которая предполагает 100%-е завершение проектирования до перехода к разработке.»  Уфф, я что-то уже совсем запутался:). Так зачем вам таки тогда requirements management процесс вообще (а именно его мы и обсуждаем, по крайне мере я именно его описываю)? На стадии разработки требований, для отслеживания того, какой аналитик и что добавил в документ? Остальная команда еще проект не колбасит? Тогда вам вся эта формальщина типа истории изменений и не нужна — пишите просто документ. И визуальное оформление изменений — для кого его делать?

    Поделиться:

    Цитировать

    09.10.2013 в 15:35 # 16495
    Аватар (Alena)
    Alena
    Подписчик
    «Так она и изменений не предполагает:). Зачем тогда вам версионность и изменения в требованиях?»

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

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

    Герман, не хотела вас запутать :) Попробую внести ясность. На стадии разработки требований действительно нет необходимости вести историю изменений. Мы и не планируем, т.к. на стадии разработки требований изменения — это норма. До подписания создаются версии документа, например, по итогам обсуждения требований на совещании, в случае внесения изменений другим аналитиком, получения правок/комментариев от заказчика и т.п. В каждой конкретной ситуации аналитик сам определяет, выделять ему изменения в новой версии или в этом нет надобности. Но вот наступил торжественный момент — заказчик подписал документ (назовем его ТЗ) и тем самым подтвердил, что он хочет получить в итоге именно то, что там написано. Начался этап разработки, затем тестирования, тестирования заказчиком. И тут заказчик говорит, что ему еще жизненно необходим какой-нибудь «розовый слоник» и без него вся разработка не имеет смысла, а на этапе проектирования он об этом забыл/не подумал/не знал. Причины изменений, как вы понимаете, могут быть самые разные. И команда принимает решение сделать «розового слоника». А в ТЗ сведения о «розовом слонике» не вносятся, документ ведь подписан и не подлежит изменению. Проходит год и тот же клиент обращается (в рамках технического сопровождения или нового проекта) с просьбой дорисовать слонику бантик. Аналитик открывает ТЗ и вообще не видит там требований про «розового слоника». Вероятно, где-то это требование зафиксировано в виде задачи разработчику, но ее еще нужно найти. Именно поэтому есть смысл вести историю изменений после подписания документ и выделять это все цветами, ссылками и т.д. И хочется, чтобы это все было правильно, красиво, быстро, удобно, в общем, в лучших традициях.

    Надеюсь, теперь будет понятнее, что я имею ввиду :)

     

     

    Поделиться:

    Цитировать

    09.10.2013 в 15:58 # 16496
    Алена, спасибо за детальность. Может к нам кто-нибудь еще подключится, увидев такую интересную беседу:).

    «И тут заказчик говорит, что ему еще жизненно необходим какой-нибудь «розовый слоник» и без него вся разработка не имеет смысла, а на этапе проектирования он об этом забыл/не подумал/не знал.» 

    Я может что-то путаю, но как-то это идет вразрез с классическим водопадом. В принципе, не суть важно, как назвать модель разработки. Я понял, что у вас нет итераций, все стадии проходятся последовательно, но в любой момент заказчик может захотеть слоника. И пошел опять водопад:).

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

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

    Ну по-моему это попытка придумать workaround там, где его быть не должно. Аналитик ну просто обязан увидеть в документе слоника, чтобы дорисовать ему бантик. Но вообще, как-то это совсем не айс — имхо вам нужно либо процесс менять на адекватно итеративный (и чтобы ожидания всех сторон по поводу деталей процесса совпадали), либо отказывать клиенту в слониках и бантиках (не лучший вариант, но, собственно, а кто просил waterfall?:)).

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

     

    Поделиться:

    Цитировать

Показано 15 ответов - от 1 до 15 (всего 29)

Вы должны авторизироваться для ответа в этой теме.