Правила подготовки хорошей технической документации23.05.2022 14:46

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

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

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

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

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

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

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

• Функционал и специфика приложения, описанные в ФО. Если вам требуется система для работы с большим объемом аналитических данных, то стоит сделать упор на те инструменты, которые умеют быстро и качественно обрабатывать информацию. Контент-ориентированные сервисы, фото- и видео-хостинги, требуют качественных систем хранения данных. В случае, если вам нужен блог, сделайте акцент на поисковый движок.

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

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

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

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

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

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

По завершению этапа или целого проекта, мы направляем все наработки в тестирование, не забывая техническую документацию. На основании нее QA-инженеры сделают свои выводы о том, совпадают ли наши ожидания и реальность, составят баг-лист.

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

Теперь, когда все готово, передаем наш проект заказчику и запускаем этап приемки. И здесь нам снова потребуется документация. Заказчик будет проверять, соответствует ли сайт ФО, макетам, отвечает ли требованиям к отказоустойчивости, времени ответа сервера, нагрузки, а также требования к устройствам, на которых приложение должно поддерживаться. Если приложение полностью соответствует документации, то шансы на быструю и безболезненную приемку стремятся к 100%.

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

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

Полный текст статьи читайте на CMS Magazine