Как отслеживать запросы на изменение функционального документа

TL;DR

Ваше предположение о том, что вам нужно отслеживать изменения в нескольких версиях, ограничивает ваши возможности управления изменениями. То же касается и вашего использования формата Microsoft Word. Я бы пересмотрел оба, если вы не можете:

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

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

Типы артефактов документов

Живые документы по сравнению с базовыми документами

Живой документ меняется по ходу проекта. Например, документ спецификации может получать обновления, когда функция foo заменяется на функцию bar или когда каким- либо образом изменяется функция baz . Этот тип живого документа может иметь подписи или утверждения, но он не предназначен для сравнения с устаревшими версиями самого себя, и поэтому его относительно легко поддерживать.

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

Ублюдочные документы

Я намеренно использую термин « ублюдочные документы » вместо «гибрид» или «совместное редактирование», потому что потребность в сложном отслеживании изменений обычно является результатом специального редактирования. Например, если вы передаете документ 37 людям, каждый из которых может вносить изменения непосредственно в документ, эти изменения необходимо объединить, разрешить конфликты и реализовать некоторую отслеживаемость изменений.

Назначение права собственности на документ для сохранения здравомыслия

Бесплатные изменения — это, как правило, просто Плохая идея™. Я настоятельно рекомендую более простой подход, где:

1. Документы имеют одного владельца.
2. Документы нумеруются строками.
3. Люди могут отправлять запросы на изменения, ссылаясь при необходимости на номера строк, владельцу документа.
4. Владелец документа вносит изменения и по мере необходимости представляет их в орган по утверждению.
5. При необходимости запросы на изменение можно сохранить как исторические артефакты.

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

Ценность отслеживания исторических версий

Есть ли в этом какая-то ценность — вопрос политический. С практической точки зрения то, чем раньше были спецификации , менее полезно, чем то, что продукт/функция должен делать сейчас .

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

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

Отслеживание исторических изменений отдельно от управления изменениями

То, как вы это сделаете, во многом зависит от вашей технической реализации процесса. Если вы должны придерживаться MS Word, вы можете рассмотреть:

1. Всегда держите отслеживание изменений.
2. Добавляйте скрытые заметки, связывающие определенные изменения с людьми, собраниями или вехами, которые не фиксируются отслеживанием изменений.
3. Скройте изменения/примечания, если только вы не занимаетесь археологией документов.

Это работает до определенного момента, но довольно быстро становится беспорядочным и запутанным. Если вы используете более гибкий формат, такой как OpenOffice или Markdown, или даже просто утилиту для вывода текста из Word в ASCII при необходимости, вы можете хранить текстовые версии в системе управления исходным кодом, такой как Git. Лично я часто использую Markdown или AsciiDoc в качестве собственного формата документа, чтобы я мог хранить текстовые версии в Git и использовать Pandoc для красивой печати документов в формате PDF, HTML или Word, когда это необходимо.

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

Пример модели владельца документа с контролем версий

В качестве примера модели владельца документа в сочетании с текстовым исходным форматом и системой контроля версий рассмотрим следующее. Если Боб является владельцем документа, а Алиса недостаточно сообразительна, чтобы редактировать Markdown или фиксировать изменения в Git самостоятельно, тогда Алиса может отправить Бобу запрос на изменение документа, говоря:

Пожалуйста, измените строку 17, чтобы сказать «эмбигген виджета» вместо «уменьшить монолит».

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

Опции на основе текстового процессора

Ваш пробег будет сильно различаться, если вы не используете собственный текстовый формат или не используете систему контроля версий. Однако аналогичные вещи можно проделать (хотя и более ограниченным способом) с документами Word и LibreOffice, каждый из которых поддерживает различные типы отслеживания изменений , управления версиями документов и сравнения версий .

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

Распространенная проблема. Есть несколько подходов, но это тот, который я использую:

1. Каждое изменение или набор изменений фиксируются в новом документе запроса на изменение. Документ CR должен фиксировать новые требования настолько подробно, насколько это необходимо для а) их утверждения б) выполнения анализа функциональных требований в) разумной оценки усилий, необходимых для развертывания изменения (не только разработки, но и всех последующих влияние развертывания изменения). Убедитесь, что нужные люди в команде разработчиков участвуют в обзоре/подписании, чтобы они знали, что будет дальше.

2. Каждый CR оценивается советом проекта/предприятием/спонсором/кто-то, кто наиболее подходит, чтобы определить, стоит ли платить стоимость изменения, учитывая выгоды, которые оно принесет.

3. Если CR одобрен для продолжения, он переходит к этапу детального функционального анализа. Обязательно сообщите команде разработчиков, что она была одобрена, чтобы они знали, что будет дальше. Ранее утвержденный документ обновляется до новой второстепенной версии, т. е. от версии 1.0 до версии 1.1 (с сохранением копии исходной версии). Отслеживание изменений включено, и документ обновляется во всех отношениях, чтобы покрыть CR. В истории редактирования вы указываете, что эта новая версия содержит поправки, относящиеся к CRxxx, и, что довольно важно, перечисляете изменения заголовков в части истории редактирования спецификации, например, раздел 1.2 изменен, чтобы включить новый виджет, раздел 2.7.1 изменен, чтобы включить новый виджет в области интеграции и т.д. и т.п.

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

5. Повторяйте столько циклов обзора/изменения, сколько необходимо, пока подписанты не подпишут измененную спецификацию. Затем сохраните его в новой копии, увеличьте номер версии до следующего целого числа (т. е. с версии 1.3 до версии 2.0), добавьте строку в свой раздел истории изменений с комментарием «Утвержденная версия» И ПРИНИМАЙТЕ ВСЕ ИЗМЕНЕНИЯ. Сохраните его в центральном расположении проекта, заархивируйте все предыдущие версии и раздайте всем, кому он нужен, с инструкциями о том, что он заменяет все предыдущие копии. Пройдитесь по нему с командой разработчиков, обсудите изменения, спланируйте изменения в проекте и убедитесь, что все разработчики готовы.

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

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

2. Люди машут изменениями, не документируя их, не оценивая и не анализируя влияние.

3. Люди только просят разработчиков оценить изменения/добавления и забывают включить команду тестирования/контроля качества, команду аппаратного обеспечения, команду инфраструктуры, менеджера по выпускам, бизнес-аналитиков и команду MI, которые должны иметь дело с нисходящие данные и предоставить измененную отчетность... и т.д. и т.п. Не делайте этого - отправьте раунд CR всем отделам, участвующим в проекте, чтобы они могли оценить влияние изменения, а затем принять во внимание это влияние и стоимость в бюджеты проектов.

4. Люди не ведут журнал CR, поэтому, когда их становится больше трех, все становится немного запутанным.

5. Люди не хранят бумажный след версий и документов CR, поэтому через год становится невозможно выяснить, что и когда было изменено.

6. Люди никогда не возвращаются, принимают изменения и отключают отслеживание. Таким образом, изменения накапливаются от версии к версии, и в конечном итоге документ невозможно прочитать должным образом.

7. Люди говорят: «Давайте просто внесем изменения, а позже мы догоним все слияния документов»... Это НИКОГДА не происходит, и, прежде чем вы узнаете, где вы находитесь, проект указывается в 23 разных местах, каждое из которых имеет оттенки версий, понимания. и оценки.

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