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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Filters

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

Filter-Port

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

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

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

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

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

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

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

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

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

Архитектура

Лучше техлид или 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 😉

Источник: https://iampm.club/blog/na-proekte-net-tehnicheskoj-dokumentaczii-s-chego-nachat/