Версионирование и согласование
Вопросы про жизнь документа во времени довольно точно отделяют тех, кто вёл проект дольше квартала. Здесь спрашивают про процедуры, а не про содержание, и заготовленных ответов из статей на эту тему почти нет.
Стержень: у документа есть история, у каждого изменения - причина и оценка влияния, у согласования - конкретный ответственный человек, а не список отдела.
// Формулировки: «зачем история версий?», «кто согласовывает изменение?», «документ и код разошлись - что делаешь?»
История и причина изменения
История отвечает на три вопроса, которые возникают постоянно: что изменилось с прошлого согласования, когда появилось это требование, кто его внёс. Без неё каждое согласование приходится делать целиком заново - люди не помнят, что читали в прошлый раз, и перечитывают весь документ или, чаще, не перечитывают вовсе.
К самому изменению прикладывают причину и оценку влияния. Причина важнее, чем кажется: через полгода никто не вспомнит, почему требование сформулировано именно так, и кто-нибудь предложит вернуть прежнюю, более логичную на вид формулировку - ту самую, от которой отказались по веской причине.
// Отсутствие версий бьёт не сразу, и в этом его коварство. Первые месяцы всё прекрасно. Больно становится через год на разборе инцидента или в споре с подрядчиком, когда надо показать состав требований на дату подписания акта, а есть только текущая редакция.
Кто согласовывает
Согласование имеет смысл ровно тогда, когда его даёт тот, кто отвечает за последствия: владелец процесса, представитель безопасности, архитектор - в зависимости от того, что именно задето изменением.
Список «всех участников проекта» превращает процедуру в ритуал. Подписывают не читая, потому что каждый рассчитывает, что прочитают остальные. Ответственность размывается до нуля, а срок согласования растёт линейно с числом участников: восемь человек по два дня каждый - это три недели на правку в одно предложение.
// Полезное упражнение, которое стоит проделать в начале проекта: заранее назвать владельца решения по каждой области требований. Кто решает про расчёт скидок, кто про персональные данные, кто про интеграции. Тогда вопрос не ходит по кругу неделю в поисках того, кто возьмёт на себя ответ.
Когда документ разошёлся с кодом
Расхождение - это симптом, а причин у него ровно две, и лечатся они противоположно. Либо поведение изменили осознанно и забыли обновить документ: тогда правится документ. Либо реализация отклонилась от согласованного без всякого решения: тогда это дефект, и правится код.
Определить, какой случай перед тобой, можно только по истории решений - было ли решение об изменении и кто его принимал. Отсюда и первый вопрос при разборе, а не спор о том, что правильнее.
Считать правдой код по умолчанию опасно, хотя соблазнительно: так узакониваются случайные отклонения. Через год половина системы работает не так, как договаривались, и все уверены, что так и было задумано.
// Корень проблемы обычно лежит в другом месте: обновление документации не входит в определение готовности задачи. Пока это работа «когда будет время», её не делают никогда - времени не бывает.
Как отвечать: «Система восемь лет, команда сменилась дважды. Что документировать?»
Решения и их причины. Что система делает, новая команда прочитает по коду и интерфейсу за разумное время - это восстановимая информация. Чего она не восстановит никогда - почему выбрали именно такой способ, какие варианты рассматривали и отвергли, какое ограничение при этом учитывали. Без записанных причин наследники либо заново предлагают отвергнутые идеи, либо ломают работающее, не понимая, от чего оно защищало. Веду это короткими записями по каждому значимому решению: контекст, рассмотренные варианты, выбор, последствия - половина страницы на решение. А описание экранов и полный перечень функций устаревают быстрее всего и окупаются хуже всего, поэтому на них я бы силы не тратил.
Кандидат расставляет приоритеты по критерию восстановимости информации, а не по формальному составу документов. Это редкий и очень практичный критерий: он сразу отвечает, что писать, а что нет.
На чём валятся
- −− Ведут требования без версий и не могут доказать их состав на дату приёмки.
- −− Не фиксируют причину изменения - через полгода решение выглядит произволом.
- −− Согласовывают со всеми подряд и получают формальные подписи вместо чтения.
- −− Считают правдой код по умолчанию и узаконивают случайные отклонения.
- −− Не включают обновление документации в определение готовности - она перестаёт обновляться вовсе.
Проверьте себя
Пять вопросов из банка по этой подтеме. Всего их 12, остальные разбираются в тренажёре.
- Что стоит приложить к изменению согласованного требования?A)Обоснование и оценку влиянияB)Скриншот переписки с заказчикомC)Новый номер версии всего документаD)Подпись каждого участника команды
показать ответ и разбор
+A)Обоснование и оценку влияния// разбор: Через полгода никто не вспомнит, почему требование выглядит именно так. Причина изменения и список затронутого превращают правку из загадки в решение с историей. Это же защищает от повторного захода на те же грабли, когда кто-то предложит вернуть прежнюю формулировку.
- Требования ведут в вики без явных версий. Какой момент станет болезненным?A)Поиск по документу станет медленнееB)Вырастет число страниц в пространствеC)Доказать состав требований на дату приёмкиD)Понадобится сменить инструмент на другой
показать ответ и разбор
+C)Доказать состав требований на дату приёмки// разбор: Пока все помнят договорённости, отсутствие версий незаметно. Больно становится на разборе инцидента или в споре с подрядчиком через год, когда нужно показать, каким требование было на момент подписания акта. По истории правок вики это восстанавливается плохо, а иногда никак.
- Кто должен согласовывать изменение требования?A)Участник команды, заметивший проблемуB)Только руководитель проекта единоличноC)Тот, кто отвечает за затронутую областьD)Все участники проекта без исключения
показать ответ и разбор
+C)Тот, кто отвечает за затронутую область// разбор: Согласование имеет смысл, когда его даёт тот, кто отвечает за последствия: владелец процесса, представитель безопасности, архитектор — в зависимости от того, что задето. Список «всех подряд» превращает согласование в ритуал: подписывают не читая, а ответственность размывается до нуля.
- Документ и код разъехались: в системе поведение одно, в спецификации другое. С чего начать разбор?A)Считать правдой код и переписать документB)Считать правдой документ и завести дефектC)Оставить как есть до следующего релизаD)Выяснить, было ли решение об изменении
показать ответ и разбор
+D)Выяснить, было ли решение об изменении// разбор: Расхождение — это симптом, а причин две. Либо поведение изменили осознанно, но не обновили документ: тогда правится документ. Либо реализация отклонилась от согласованного: тогда это дефект. Определить это можно только по истории решений, поэтому первым делом ищут, принималось ли изменение.
- Почему полезно хранить требования рядом с кодом в системе контроля версий?A)Так документ занимает меньше местаB)Изменения текста и кода едут одной правкойC)Так требования становятся доступны публичноD)Система версий сама проверяет непротиворечивость
показать ответ и разбор
+B)Изменения текста и кода едут одной правкой// разбор: Когда описание лежит рядом с кодом, оно правится в том же изменении и проходит то же ревью — рассинхрон становится физически труднее. Появляется и история: видно, каким было требование на момент любого релиза. Минус подхода в том, что нетехническим участникам туда неудобно ходить.
дальше
Теорию прочитали. Навык ставится повторением
В Сеньорчике эта подтема идёт в ежедневных сессиях: движок возвращает её, пока ответы не станут уверенными, и ведёт прогресс отдельно по каждой подтеме. Теория внутри тоже бесплатна, лимит только на количество вопросов в день.