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

Документирование – это процесс создания печатного документа для сопровождения программного обеспечения или приложения. Документ содержит в себе описание функционала системы и принципов его работы.

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

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

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

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

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

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

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

• Кроме того, текст должен быть грамотным. Речь идет не только о грамматике и пунктуации, но и о стиле письма. Описание не должно содержать сложных технических терминов и жаргонов, которые будут понятны только программистам.

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

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

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

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

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

Условно все документы разработки можно классифицировать и разделить на четыре типа:

• Проектная, её ещё называют архитектурной.

• Техническая.

• Пользовательская

• Маркетинговая.

Ниже расскажем подробнее о каждой из них.

Проектная документация программного обеспечения.

Дает общее описание проекта в целом. То есть, как это будет выглядеть в конечном итоге, и почему именно так, а не по–другому.

Ниже рассмотрим основные элементы документа, которые помогут выстроить эффективную архитектуру ПО.

• Область действия системы.

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

• Цели и ограничения.

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

• Представления и перспективы.

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

• Диаграммы компонентов.

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

• Последовательность.

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

• Модели данных.

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

• Нефункциональные требования.

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

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

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

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

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

• Doxygen – кроссформенная платформа для документирования исходного кода программного продукта с поддержкой таких языков программирования, как C++, Си, Objective-C, Python, Java и многих других.

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

Doxygen поддерживает генерацию документации в таких распространенных форматах, как HTML, LATEX, man, RTF и XML. При желании можно конвертировать в форматы CHM, PDF и PostScript.

• Javadoc – генерирует документацию в HTML–формате на основе комментариев, написанных на языках Java от Sun Microsystems.

Чтобы анализировать структуру Java–приложения, платформа предоставляет API для создания доклетов и тэглетов.

Javadoc является стандартом для создания документации класса Java, поэтому часто процесс генерации HTML–документации происходит с его использованием.

NDoc – генератор документации по коду для инфраструктуры общего языка. Доступен по лицензии GNU General Public License.

Платформа создает документ на основе двух источников: первый – файл assembly, который появляется через компиляцию исходного кода, второй – заранее сгенерированный файл документации XML, созданный путем синтаксического анализа кода для получения специальных комментариев.

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

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

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

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

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

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

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

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

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

• Вводное руководство – уровень для новичков. Позволяет последовательно шаг за шагом погрузить пользователя в материал, чтобы выполнить определенные задачи.

• Тематическое руководство – в нем каждая глава раскрывает определенную тему программы. Это уже более продвинутый уровень пользователей.

• Справочное руководство – рассчитано на продвинутых пользователей, которые, вероятно, знают продукт и ищут что–то конкретное.

Процесс создания пользовательской документации можно автоматизировать с помощью специальных инструментов. Рассмотрим несколько популярных вариантов.

Dr.Explain

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

HelpnDoc

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

ClickHelp

Веб–сервис для создания документации. Особую пользу принесет проектам, которые стремятся выйти на международный рынок, так как осуществляют перевод руководства на любой язык при помощи Google. Имеет систему полнотекстового поиска, что облегчает поиск конкретного термина по всей существующей документации.

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

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

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

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

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

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

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

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

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