Управление конфигурацией. Не забыть про документацию?

Одной из важнейших подпрактик практики управления жизненным циклом является управление конфигурацией. Напомним, что конфигурация – это текущее актуальное состояние системы (воплощения системы: всех частей на всех системных уровнях) и её описаний в их соответствии. А управление конфигурацией – это отслеживание, что конфигурация воплощения системы и описания системы известны и соответствуют друг другу. Сама же конфигурация может быть описана (defined) и документирована (described). Документация системы всегда является документацией каких-то конфигурационных единиц данной системы. Проанализировал несколько проектов, которые ведутся в подразделении и обнаружил, что описание системы, изложенное в ее документации, отличается от реального функционала системы. И если процесс разработки частей системы, их перенос между средами более-менее выстроен, то про документацию в этом процессе часто забывают.

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

Цель документации – это передача знаний. Между членами проектной команды, между Заказчиком и Исполнителем. Основными «потребителями» документации системы являются пользователи системы и сотрудники, отвечающие за ее эксплуатацию. Также ими являются члены команды разработчиков, включая программистов, инженеров по требованиям, тестировщиков итд.

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

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

Считаю, что основной причиной, по которой про документацию часто забывают, является то, что ей не пользуются. Чтобы труд по созданию документации не пропал даром, она должна использоваться. Чем больше у документации читателей, и чем чаще они обращаются к ней, тем более они будут требовательны к автору, тем выше будет качество документов. Никому не нужный документ – некачественный документ. Чтобы повысить качество документации, необходимо сделать так, чтобы она начала активно использоваться.

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

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

Мне кажется, что дело еще и в отсутствии осознанного выделения документации, как важной составляющей разработки. Говоря по простому, часто документация не включена в defenition of Done, воспринимается, как что-то сильно второстепенное.

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

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

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

На самом деле документация не разрабатывается должным образом и не поддерживается в актуальном состоянии просто потому что на это нет запроса. Нет потребности от надсистемы. И это может быть объективно. Например проект - распил или примерно распил) или сдали систему и ладно - так бывает на госухе, или ЖЦ системы год-два-три. Зачем тратиться на ее дорогое качественное документирование? Посмотрите по-честному на ваши системы , что делаете в проектах. Им жить сколько? Если гола три, то не о чем и говорить. Проще и дешевле посадить “китайцев” на линию поддержки и закрыть этим все вопросы.

«Госуха» и тп. в посте не рассматривается. Об этом есть упоминание. ЖЦ наших систем больше трех лет – первый контракт обычно на года два, далее погодовОе развитие.
А откуда «китайцы» узнают, как работает система и как работать с системой? Ведь служба поддержки это такие же стейкхолдеры как и те, кто использует систему для бизнеса. И у нее есть запрос на информацию о том, что это за фрукт, который они должны поддерживать. Этого запроса не может не быть по определению. И этот запрос они могут удовлетворить экспериментально методом научного тыка или дергая разработчиков «а как это работает, а как это сделано». В первом случае есть риск поломки системы, второй – крайне неудобен для разработчика. Может со стороны разработчика было бы менее трудозатратно сделать удобную документацию?
Говорить о том, что документация не делается, потому что нет запроса, на мой взгляд, инфантильно. А какой вид документации мы можем предложить? Сотни страниц Word во всяких Пояснительных записках и Руководствах Пользователя? На такую документацию запроса нет, совершенно согласен. Но вместо того, чтобы использовать это для оправдания, лучше искать варианты, каким удобным способом передать внешним ролям информацию о том, как работает система. Об этом, собственно, и пост. Может это будут wiki, видеоролики, комиксы, мультики, справка в интерфейсе системы или что-то еще или все вместе. Я сейчас фантазирую, конечно, не факт, что это все реально. Я пока не знаю удобного способа. Но надо искать, это точно.
И напоследок…на самом деле никто не знает как оно на самом деле :).

У меня встала задача описание бизнес процессов и я пришел к тем же выводам, что и вы. Без организации общедоступного рабочего пространства невозможно сделать документацию, чтобы ей пользовались. В качестве общего рабочего пространства было выбрана Coda.io Был написан первый регламент бизнеспроцесса, уведомлены все заинтересованные лица, все сказали ок, будем пользоваться, пиши еще. Через неделю после публикации описания БП, на совещании зашла речь, об изменении данного бизнес процесса. И я сильно удивился, что вместо того чтобы открыть БП и посмотреть какую стадию нужно менять, начали привлекать затоков данной процедуры чтобы они рассказали. В общем чувствую, что путь длинный и не простой пользования документацией. Должна сформироваться привычка обращения к документации, а она формируется если она полезна. Затраты времени на открывания документа и поиск в нем информации должны быть меньше чем поиск знатока.