Содержание технической документации и методы разработки

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

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

Документация по сопровождению программы
Документация по сопровождению программы описывает программу с точки зрения её разработки. Эта документация необходима, если программа предполагает изучение того, как она сконструирована.
Сопровождение - это продолжающаяся разработка, поэтому если созданную программу совершенствуют и обновляют не сами её создатели, то чаще всего привлекают специальную команду разработчиков - сопроводители. Этой команде придется иметь дело с такой же документацией, с той лишь разницей, что им нужно будет подробно просматривать и изучать документацию, созданную первоначальными (основными) разработчиками, с той целью, чтоб понять строение и процесс разработки изменяемой программы, и внести в эту документацию необходимые изменения, повторяя в значительной степени технологический процессы, с помощью которых создавалась первоначальная программа.
Документация по сопровождению программы можно разбить на две группы:

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

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

Документация для программного обеспечения – это справочный текст и визуальная информация, описывающие и отображающие процесс разработки, производства, эксплуатации и сопровождения программного продукта, его потребительские свойства и технические характеристики.
Виды документации для программного обеспечения
В соответствии с таким определением, техническая документация по ПО состоит из четырёх основных типов:
• Проектная – включает описание основных положений, используемых при создании ПО и рабочей среды.
• Техническая – алгоритмы, код, интерфейсы, АРI.
• Пользовательская – руководства для пользователей программы.
• Маркетинговая – содержащая рекламную информацию о продукте.
Проектная документация, как правило, программный продукт описывает в общих чертах. Например, программист в проекте может обосновать, почему структуры данных именно таким (а не иным) образом организованы. Почему именно таким образом сконструирован тот или иной класс. В проекте выделяются паттерны. Часто даются указания, как выполнять модернизацию программы.

Техническая документация - не только указывает конкретные коды. Она, как правило, также описывает различные аспекты того, что этот код делает. Она имеет явно выраженный технический характер и используется в основном для описания и определения API, алгоритмов и структур данных. При её составлении возможно использование генераторов документации (Doxygen, NDoc, javadoc и др.), что даёт возможность постоянно поддерживать такую документацию в актуальном состоянии. В последнем случае техническая документация является частью исходного кода. Тогда одни и те же инструменты можно использовать как для сборки программы, так и для сборки в то же время документации к ней.
Хорошая пользовательская документация состоит из:
• вводного руководства, где рассматриваются общие вопросы выполнения типичных задач;
• тематического, где каждая глава посвящена разъяснению какого-либо раздела эксплуатации программы;
• алфавитного справочника, для опытных пользователей, хорошо знающих, что нужно искать.
Маркетинговая документация используется для рекламы как самого программного продукта и его составляющих, так и других программных продуктов компании. Она часто информирует покупателя о свойствах продукта, объясняет его преимущества перед конкурирующими решениями. Часто бывает так, что именно коробка продукта и другая маркетинговая информация дают самое чёткое и простое представление о способах использования и возможностях программы.

Стандарты для разработки ПО
Основой для создания любой документации на программные продукты служат стандарты.
Современных стандартов по разработке технической документации для программного обеспечения в Российской Федерации до сих пор нету ещё со времён СССР. Хотя стандарты и модернизируются. Последнее обновление ГОСТ 2.015-2013.
В таких условиях IT-компании вопрос разработки документации для программного обеспечения решают по-разному. Одни пытаются копировать и внедрять западные стандарты. Другие – использовать отечественные. Третьи – создают свои собственные.
В настоящее время действуют следующие стандарты документирования:
ГОСТ 19.201 ( Единая система программной документации (ЕСПД);
ГОСТ 2.015-2013 (Единая система конструкторской документации (ЕСКД);
ГОСТ 34.602 (Комплекс стандартов на автоматизированные системы (КСАС).