Обучение онлайн хорошо тем, что можно задать вопрос и получить развернутый ответ от спикера, на тему, актуальную текущему проекту.
В сегодняшней статье — ответ от Павла Устинова, спикера курса 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 😉