Введение

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

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

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

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

Суть

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

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

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

Функциональный заказчик — определяет последовательность действий в программном обеспечении для достижения результата. Любит описание процессов в нотациях (лучше всего заходит BPMN 2.0)

Руководитель проекта/продукта — определяет последовательность работ для достижения целей проекта/получения выгод от продукта. Редко когда пишет документацию, либо «борщит» пытаясь заполнить всё по PM BOK последней редакции, используя шаблоны полученные во время сертификации (сам грешил:))))

Аналитик — формирует задание на разработку. Есть разные подходы, лучше опираться на пожелания и требования команды. Разработчики, в большинстве своём, идут на встречу и объясняют, что именно им необходимо

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

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

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

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

Эксплуатация — применяет документацию, которую подготовили в инфраструктуре. Иногда на неё жалуются(

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

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

• Цели проекта/продукта — как будет выглядеть результат проекта. Помогает при постановке задач проекта, формировании Epic и Story (на habr.com есть отличные статьи на эту тему).

• Вехи проекта/продукта (дорожная карта) — контрольные точки реализации проекта. Помогают оценивать, туда ли мы идём, способствует ли результат конкретной вехи достижению целей проекта.

• Карта пути клиента (Customer Journey Map) — описание пути клиента.

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

• Компонентную схему. Содержит структурную диаграмму, которая отображает структурные компоненты и связи между компонентами.

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

• Описание каналов взаимодействия. Содержит описание способов обмена информацией и характеристик каналов обмена.

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

• Описание элементов интерфейса и компонентов

• Описание шрифтов, цветов и т. д.

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

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

• Описание сквозных бизнес‑процессов. Описание от точки появления потребности в системе до точки удовлетворения потребности.

• Описание примеров использования (Use Case).

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

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

• ER диаграмма

• Диаграмма последовательности (sequence diagram)

• Описание методов взаимодействия (REST, SOAP, GRPC и т. д.)

• Описание взаимодействия с брокерами сообщений и т. д.

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

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

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

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

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

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

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

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

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

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

3. Можно разбить свою wiki‑систему на 2 части. Это позволит понимать, что сейчас разрабатывается, а что уже применяется.

   • Работающий функционал. За него отвечает служба технической поддержки.

   • Разрабатываемый функционал, за который отвечает аналитик.

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

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

5. Документ должен иметь ответственного.

6. Текст должен быть понятен психически здоровому человеку.

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

Тяжело читать письмо из Простоквашино:))) Мой трудовой опыт показывает, что это самое цитируемое описание состояний дел на проекте.

Выводы

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