Привет, Хабр! Меня зовут Татьяна Шуравина, я системный аналитик Innovative People, работаю на проекте в банковском секторе. Вместе с командой оптимизируем и автоматизируем операции сотрудников банка для обслуживания юридических лиц. В своей первой статье я рассказывала, как стать системным аналитиком без специального образования. Сегодня хочу поделиться с теми, кто начал свой путь в аналитике, тонкостями магического процесса ведения проектной документации. Не для кого не секрет, что зачастую бывает такое, что система есть, а документации, чтобы понять, как она работает, нет. В статье расскажу, какие есть подходы к ведению документации, зачем это нужно и поделюсь практическим опытом.
Что относится к проектной документации?
На протяжении всего проекта команда в соответствии со своими компетенциями ведет разного рода документацию, которая содержит информацию о каждой вехе проекта. Это несколько этапов от подготовки проекта до внедрения в промышленную эксплуатацию. Их структура и суть должны быть отражены в соответствующем виде и доступном для заинтересованных лиц месте.
При использовании разных методологий ведения проектов названия этапов могут отличаться, но перечень работ сохраняется вне зависимости от подхода.
Итак, на первом этапе ведется предпроектная документация, которая описывает подготовку для запуска проекта и крупными мазками — план‑график проекта.
Далее — этап проектирования, на котором рождаются и разрабатываются проектные решения на основании входных данных с этапа предпроектной подготовки.
Едем дальше: этап реализации проекта. К этому этапу относится документация, с которой работает команда разработки. Тест‑кейсы и данные для проведения функционального, интеграционного и бизнес‑тестирования. В своей статье я подробно остановлюсь на ведении документации, необходимой для системного анализа и разработки.
Завершающим этапом является подготовка и переход к ОПЭ, реализованного проекта, в соответствии с документацией на всех предыдущих этапах продукта. Инструкции пользователей и регламенты процессов — выходные документы заключительного этапа.
Зачем нужны правила оформления документации?
Редко встретишь человека, которому нравятся бюрократические замашки, оформление документов в соответствии с придуманными кем‑то стандартами и шаблонами. Всегда что‑то не нравится и хочется изменить под себя. Но, исходя из опыта работы на проектах, понятное и удобное ведение документации, для всех членов команды и потомков, имеет следующие преимущества:
1) сокращение сроков первичных согласований на предпроектном этапе;
2) быстрый онбординг новичков и адекватная оценка сроков проекта;
3) легкость в передаче экспертизы коллегам в соответствии с разными компетенциями, представлении продукта заинтересованным лицам;
4) прозрачность и понимание для коллег, сопровождающих систему после внедрения.
Документация, необходимая для системного анализа и начала разработки продукта
Для начала системного анализа в моей команде аналитику достаточно иметь 3 основные составляющие:
согласованный вижн;
бизнес‑требования;
макеты интерфейсов.
Вижн — документ‑изложение проектного решения и основа для разработки. На вижне, обычно, отображена архитектура проекта, т. е. взаимодействия реализуемой или дорабатываемой системы с другими системами и данные, которыми обмениваются потребитель и поставщик. Также указаны флоу процессов, которые реализуются, в соответствии с данным вижном.
Бизнес‑требования могут приходить в аналитику в разных вариантах: в виде оформленного документа в ворде или user‑story, в которой описано поведение системы сейчас (as is) и как должно быть, в соответствии с требованиями заказчика (to be).
Макеты ui также важны для проработки функционала, описанного в требованиях бизнеса и для оценки трудоемкости задач для разработки.
Ведение документации на примере одного проекта
На проектах применяются разные подходы к ведению и оформлению документации, также как и места хранения информации. Зачастую рабочее пространство выбирать не приходится, так как приходя на проект, заказчик уже использует конкретные инструменты для организации проектной работы.
Рассмотрим два распространенных метода ведения проектной документации на моей практике:
1) ведение спецификаций требований к АС (СТАС) по ГОСТу в электронном виде с загрузкой документа в электронный архив;
2) ведение документации в электронном виде в рабочем пространстве, которое используется на проекте в соответствии с определенной структурой;
Сравним описанные выше подходы на предмет удобоваримости формата работы с каждым.
Универсального рецепта нет, поэтому наиболее удобный и эффективный формат ведения документации, команда вправе выбирать сама с учетом особенностей проекта.
В данный момент я работаю на проекте, где вся информация хранится на Confluence в соответствующем проектном пространстве. Команда проекта делится на подкоманды, которые сопровождают определенные модули, которые взаимодействуют между собой. Для нас было важно создать такой подход для ведения документации, который позволяет структурированно и в едином формате отражать информацию по каждому модулю.
В какой‑то момент остро встал вопрос о том, как сделать документацию понятной, полезной и без лишней лирики. После нескольких встреч и понимания, что важно и нужно учитывать при ведении проектной документации для всех членов команды на разных этапах мы пришли к определенному результату. Для структурности и единого подхода команда разработала шаблоны для описания бизнес‑требований, системного анализа и процесса тестирования. Эти шаблоны положили в общий репозиторий в рабочем пространстве проекта.
Для аналитики мы разбили информацию на несколько разделов и подразделов:
архитектура;
-
описание процессов;
подраздел метрики;
-
база данных.
В разделе «Архитектура» отображена общая схема взаимодействия модуля с разными сервисами и сторонними системами через api. Аналитик описывает контракты для интеграции с другими системами, рисует UML‑диаграммы с последовательностью вызовов для получения данных.
Для изображения процессов используем макеты ui и описываем сценарии работы пользователя в системе с разрабатываемым функционалом, поведение системы и обработку ошибок. В этом разделе также упоминаем про ролевую модель, т. е. какие роли и права должны быть у пользователя для доступности функционала. При необходимости, если в процессе работы в системе формируются печатные формы или отчетные документы, то отражаем логику формирования и шаблон печатки.
В разделе «Метрики» описываем места, где логируются действия пользователя, названия метрик, как они интерпретируются при выгрузке отчётности. Раздел используются при необходимости.
База данных это тоже не обязательный раздел, но мы ведём его для команды сопровождения. На проекте используется в нереляционная БД — MongoDB. На страничке для БД описываем коллекции данных, которые используются для работы функционала.
Помимо корректного ведения документации не маловажным аспектом является поддержание документации в актуальном состоянии. Для этого раз в квартал мы используем перекрёстный аудит. Системные аналитики из смежных команд заполняют специально разработанные чек‑листы на соответствие документации определенным критериям. Если есть какие‑то замечания, то ответственный аналитик устраняет. Ели объем документации, которую необходимо актуализировать/добавить, слишком большой, то заводится техдолг по документации, который постепенно устраняется.
Чтобы не доводить ситуацию до критической точки, нужно придерживаться простого правила: сделали доработку — и сразу актуализировали документацию. В процессе это занимает мало времени, но эффект от такого подхода очевиден. Если не обновлять информацию в срок, то на большой дистанции можно потерять кучу времени, чтобы вспомнить все и корректно занести информацию.
Эффект от ведения документации, которое устраивает всю команду
Проекты разные и универсальных рецептов точно нет — надо делать то, что удобно и эффективно с точки зрения коммуникации для команды, которая используем документацию в своей работе. При этом не надо изобретать велосипед, на мой взгляд, нужно использовать инструменты разных подходов и пробовать, что подходит для конкретного проекта.
Полная, доступная и единообразная документация должна работать как навигатор. Мне очень нравится фраза «Порядок в голове — порядок везде». Это я к чему: структурированная определённым образом документация, которая вовремя актуализируется, может дать только положительные эффекты.
Начинающим аналитикам, хочу порекомендовать список самых используемых инструментов для ведения документации:
Google Drive для хранения разного вида файлов с общим доступом и редактированием онлайн.
Dropbox, как замена Google Drive. Если, кто‑то из сотрудников потерял телефон, то в Dropbox можно отключить доступ к этому устройству.
Confluence — общее рабочее пространство, база знаний для создания, хранения, редактирования документов.
Notion — «википодобный» ресурс. Хорошо работает для базовой документации, особенно о каком‑то продукте. В целом, можно использовать как замену Confluence и сильно экономить, потому что Notion дешевле.
Miro помогает сделать быстрое ревью документа. Похож на большой lite‑board или Paint, куда можно вставлять различную информацию: ретроспективу, анонсы, согласование дизайна со стейкхолдерами, превью дизайна с разработчиками.
Важно, какими бы инструментами вы ни пользовались, соблюдайте базовые правила:
1. Документация должна быть актуальной. Для удаленных команд с десятью часами разницы во времени онлайн оборот особенно актуален: можно быстро редактировать документ и все это видят.
2. Документация должна быть доступной. Перепроверяйте права доступа.
В течении всего жизненного цикла проекта:
выбирайте правильные инструменты для хранения и работы с документами;
создавайте навигацию, в которой сможет разобраться даже новичок;
делегируйте работу и проверяйте сделанное другими.
Так же полезными ссылками на интересные статьи:
Подход к ведению документации на ОС: наш опыт
Как научиться создавать полезную проектную документацию ИТ‑систем
Успехов всем начинающим и помните, ведение документации — это непрерывный процесс: «Вы можете откладывать, но время этого не сделает». — Бенджамин Франклин