Что такое техническая документация проекта? Кто и зачем ее пишет.

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

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

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

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

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

Техническое задание или технический проект

Техническое задание (ТЗ) и технический проект — два разных документа. ТЗ дает ответ на вопрос «что надо делать?». Как правило составляется аналитиком перед началом проекта. Технический проект составляет технический писатель. Он создается после ТЗ и отвечает на вопрос «как надо делать?».

Кто будет писать?

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

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

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

Кто такой технический писатель

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

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

Какая техническая документация нужна

Рассмотрим идеальный процесс разработки системы. Все начинается с требования заказчика зафиксировать все что должно быть реализовано в документе «Техническое задание».

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

Далее аналитик составляет ТЗ и согласует его со всеми заинтересованными сторонами. После того как собраны и утверждены все требования, можно приступать к созданию прототипов будущей системы и разработке программного обеспечения.

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

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

Соответственно, технический проект отвечает на вопрос «как делать?» и именно его составляет технический писатель.

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

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

Когда составлять техническую документацию

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

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

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

Выводы

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