ИТ – Как быть с документацией?

Введение

Документация в рамках ИТ-проекта/продукта подчас имеет необычное исполнение. Есть проекты/продукты, где на первый взгляд с документацией всё хорошо, она выходит в рамках обязательств по контракту, но вот применять её очень сложно. Бывают и обратные примеры, когда документация оформлена отлично и написана грамотно, в ней всё понятно, но она очень сильно устарела. Иногда случается всё и сразу.

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

Постановка задачи

В рамках статьи я хотел поделиться подходами к организации работы по документации. Где она образуется, кто чью использует?

Суть

Для начала определим, кто в рамках ИТ-проекта готовит документацию и где впоследствии её можно применять. Сразу оговорюсь, что подход по ГОСТ 34, ГОСТ 19 и другим регулирующим документам мне кажется очень даже неплохим, но нашей задачей будет именно формирование принципов.

Точки образования документации (кто составляет тоже укажем, но попозже)

Заказчик – формирует документацию по целям и задачам проекта. Её можно использовать как есть, но, на мой взгляд, лучше адаптировать к проекту в виде схем, пользовательских путей и т. п.

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

Руководитель проекта/продукта – определяет последовательность работ для достижения целей проекта/получения выгод от продукта.

Аналитик – формирует задание на разработку.

Разработка – генерирует минимум документации, является её пользователем. Если в вашем проекте разработка занимается созданием документации, значит что-то в нём не так.

Тестирование – пользуется документацией от аналитика.

Инфраструктура – формирует документацию для эксплуатации и развертывания проекта/продукта.

Служба технической поддержки – использует документацию от аналитика.

Эксплуатация – применяет документацию, которую подготовили в инфраструктуре.

Кто создаёт документацию в рамках реализации проекта/продукта

Руководитель проекта/продукта составляет общую картину по проекту/продукту, в которую я включаю:

Цели проекта/продукта – как будет выглядеть результат проекта. Помогает при постановке задач проекта, формировании Epic и Story (вот статья о том, что я подразумеваю под этими терминами: линк).
Вехи проекта/продукта (дорожная карта) – контрольные точки реализации проекта. Помогают оценивать, туда ли мы идём, способствует ли результат конкретной вехи достижению целей проекта.
Карта пути клиента (Customer Journey Map) – описание пути клиента.

Архитектор проекта/продукта определяет технические границы проекта, а еще подходы и методы встраивания в единую архитектуру, в которой крайне желательно видеть:

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

Дизайнер описывает гайдлайн (Web-UI kit) совместно с front-лидом. Это очень важное замечание, так как гайдлайн позволит умерить полёт творческой мысли всех участников проекта/продукта (понимаю, что творцу и заказчику визионировать не запретить, но от чрезмерного креатива скорость и качество разработки будут очень сильно страдать. Что делать тестированию без гайдлайна – это отдельный и очень специфичный вопрос). А в задачи дизайнера входит:

Описание элементов интерфейса и компонентов
Описание шрифтов, цветов и т. д.
Совместный с разработкой подбор в случае необходимости библиотеки компонентов (я видел, как стандартный элемент календаря, который есть в библиотеке, разрабатывали почти 3 месяца :), а время списывали исправно)

Бизнес-аналитик составляет описание реализуемых процессов в системе. В частности:

Описание сквозных бизнес-процессов. Описание от точки появления потребности в системе до точки удовлетворения потребности.
Описание примеров использования (Use Case).
Описание данных для тестирования (Кто-то скажет, что это вопрос тестирования, а я выражу свое несогласие. Бизнес-аналитик общается с функциональным заказчиком. Ему предстоит демонстрировать функционал, с него и данные, а у тестирования своих задач хватает).

Системный аналитик составляет техническое описание реализации программного обеспечения:

ER диаграмма
Диаграмма последовательности (sequence diagram)
Описание методов взаимодействия (REST, SOAP, GRPC и т. д.)

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

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

Инфраструктура. Сюда отнесём всё, что связанно с DevOps-методологией и эксплуатацией. Это диаграмма развертывания (deploy diagram).

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

Выделим подход к работе с документацией

Процитируем Agile-манифест: «Работающий продукт важнее исчерпывающей документации». Теперь немного поделюсь своими соображениями по этому поводу.

Чтобы продукт был качественным, как минимум необходимо чётко сформулировать цель проекта/продукта и выделить набор задач по достижению цели.

Пример: Нам всем в школе на уроке математики, а кому-то и на уроках физики рассказывали: «Для решения задачи необходимо описать: дано, найти, решение». Мы дополним этот алгоритм из школы методом решения и получим, что должно исходить от руководителя проекта/продукта.

От постановки задачи на разработку до написания руководства пользователя доходит только один документ – это пример использования. Обычно его пишет аналитик, причём с указанием основного пути, альтернативного пути и негативных сценариев.

Пример: Постановка на разработку функционала от аналитика ушла с описанием примеров использования. По ним системный аналитик сможет описать техническую часть реализации; разработка – понять, что хочет пользователь; тестирование – проверить правильность работы функционала; технический писатель – доработать руководство пользователя; а пользователь – разобраться, как работает функционал. Заметим, что большинство участников команды применяет на этапе постановки именно сформированный документ (!).

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

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

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

Пример: Мои папа и мама! Я живу хорошо, просто замечательно. У меня все есть, есть свой дом, он теплый. В нем одна комната и кухня. Я без вас очень скучаю, особенно по вечерам. А здоровье мое не очень. То лапы ломит, то хвост отваливается. А на днях я линять начал. Старая шерсть с меня сыпется, хоть в дом не заходи. Зато новая растет чистая, шелковистая, так что лохматость у меня повысилась. До свидания, ваш сын, дядя Шарик.

Тяжело читать письмо из Простоквашино.

Выводы

Документация при реализации ИТ-проекта/продукта необходима. Основной источник документов – аналитик. При правильном подходе и должном усердии можно поддерживать документацию актуальной. Важно помнить, что документации должно быть достаточно для понимания текущей ситуации и включения новых участников команды в процесс реализации ИТ-проекта/продукта.