На проекте нет технической документации: с чего начать

20 апреля 2022

  • Автор: Павел Устинов

  • Сложность: норм

  • Время: 5 мин

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

В сегодняшней статье — ответ от Павла Устинова, спикера курса TechMind, PMO в компании SOLAR Digital. 

Итак, что делать, если вы РМ на проекте в котором нет технической документации. Кому поставить задачу на ее описание и что должно быть в ней обязательно?

На проекте нет технической документации: с чего начать

Проект есть, а документации нет: разбираем причины

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

Проект динамично развивается и активно разрабатывается

Чаще всего речь идет о первых релизах проекта. В таком случае надо сразу понимать, что детальной информации по проекту собрать не получится, так как пока вы будете ее писать, код будет обновляться, и такая документация будет устаревать. 

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

Проект разрабатывается продолжительное время и уже довольно большой

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

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

Начните с таких документов: 

  • описание проекта и его архитектуры
  • соглашения разработчиков (как мы ведем разработку, каких правил придерживаемся)
  • актуальная API документация
  • описание кода сайта (phpdoc или другие, по технологиям)
  • пользовательская документация
  • перечисление, что умеет делать наше приложение (полный список функций и для чего они нужны). 

Пример с Filters и Filter-Port

Filters

Пользователь должен уметь фильтровать по различным параметрам и данным в таблице. Множественный выбор по одному фильтру должен работать, как логическое AND, т.е. если пользователь выбрал Hong Kong и Kyiv, выборка отдаст результаты только по пересечению условий, а именно, в таблице будет отображены данные только для порта Hong Kong и только для порта Kyiv.

Filter-Port

Пользователь может фильтровать по портам, может применять множественный выбор портов, в самом фильтре присутствует поиск. Список портов содержит только те порта, в которых есть терминалы. Множественный выбор по одному фильтру должен работать, как логическое OR, т.е. если пользователь выбрал Hong Kong и London, выборка отдаст результаты по обоим портам. Выбранный порт, или несколько, отображаются в дополнительной строке, как теги. Пользователь может убрать один или все теги и, как результат, фильтрация по ним отменится.

Проект сделан плохо в плане архитектуры 

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

Если в плане архитектуры на проекте все плохо, это порождает ряд проблем, с каждой из которых разобраться можно, но все в комплексе приводят к постоянной спешке и нехватке ресурсов команды. Происходит это так:

  • В проектах, где плохо решена архитектура, либо разработка велась вразрез общепринятым стандартам кодирования и канонам используемого фреймворка, поддержка часто крайне трудоемка и затруднена.
  • Поскольку все делается очень долго, возникает давление на команду, с настойчивым указанием ускориться, это вызывает постоянную спешку ребят,
  • В таких случаях вместо «давайте это зарефакторим» звучит «нужно зарелизить», и команда продолжает пагубную традицию. Хорошо, если не делается костыль-на-костыль и ситуация не усугубляется.
  • «Обещанный» рефакторинг, которого ждет вся команда, все как-то не начинается, потому что «надо же фичи релизить» или на это просто нет денег желания продукт овнера. 
  • Поскольку у нас все плохо, есть перманентный страх перед тем, что члены команды не получат ожидаемые пересмотры зарплат и «они тут навсегда».

Delivery Mind

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

В этом случае, проблема не в том, что именно документировать, а в том, чтобы начать исправлять то, что плохо написано в плане архитектуры. Самое страшное в таком проблемном проекте — что программист замалчивает проблемы в разработке, поэтому важно прежде всего понять, что переделать в архитектуре, а тогда и документацию будет писать быстрее и проще.

Сколько нужно документов и кто их должен создавать

На проекте нет технической документации: с чего начать

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

Архитектура

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

Разработчики могут отказываться документировать, если: 

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

Главное — победить возражение, что «документацию писать очень долго, это пустая трата времени, зачем, все ж и так понятно». В любом случае, нужно описать из чего состоит приложение (классы, модули/микросервисы), что общается с базой данных, файлами, как устроена передача данных на front-end.

Общие условия работы

Укажите общие условия (Developers Agreement), какой style guide, как использовать переменные (variables), функции (functions / classes methods), классы, какой code linting (если он есть), какой подход используется к организации кода (SOLID), как общаются между собой функции (functions interacting). Не должно быть сомнений, что все будет одинаково, хотя на практике так бывает далеко не всегда.

Другая базовая документация:

  • Технический стек проекта
  • Инструкции по установке на окружение: local environment and server environment. 
  • Описание работы CI/CD, если он есть и по возможности, его настройки (setup). Указать, какие скрипты что делают.
  • Внешние интеграции: какие есть, как они работают. Приложить ссылки на API документацию.
  • Можно подключить автоматический документатор кода, чтобы комментарии в коде сами генерировали документацию. Если подключите, дайте понять команде, что описывать каждую функцию (метод) подробно не надо.
  • Структура базы данных (выгружается из веб-шторма автоматически) или просто перечисление таблиц и зачем нужны.
  • Если есть unit тесты — дать перечисление, какие есть.
  • API Doc, если используете API. API Doc надо иметь подробный, с описанием методов API, параметров и структур ответов с типами данных в нем.

Остальное по вкусу и необходимости, например:

  • Инструкции пользователя
  • Тест-кейсы, где перечислено все, что тестируется.
  • Описание функциональности приложения

Тогда у вас будет хорошее описание, что делает ваше приложение, и к нему всегда можно вернуться для понимания что должно быть. Лучше всего это сможет написать QA.

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

Если справитесь, сможете создать хорошую, понятную документацию без хаоса в задачах

А если нужны системные знания технологий разработки, CI/CD, и навыки коммуникации с технической командой — приходите на курс TechMind 😉

Павел Устинов

Project Manager Officer в Solar Digital с 15-летним опытом работы в IT-сфере. Занимается разработкой мобильных приложений, сайтов, блокчейн систем. Имеет за спиной более 10 лет опыта преподавания в оффлайн и онлайн форматах.