Организация документирования программных средств

Лекция 17. Документирование программных средств

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

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

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

Методы и средства документирования каждой процедуры в стандартах обычно не раскрываются и адресуются к специальным нормативным документам различного уровня. Быстро оснащающиеся различными ме­тодами и инструментальными средствами этапы системного анализа, моделирования и проектирования ПС различных классов и назначения затрудняют стандартизацию этих процессов, достаточную для полной формализации структуры и содержания документов на программы и данные на уровне международных стандартов. Поэтому для этих этапов создаются нормативные до­кументы – шаблоны на уровне стандартов де-факто, исполь­зующие, адаптирующие и дополняющие компоненты стандартов де-юре в разумной степени. Такие нормативные документы содержат выде­ленные фрагменты стандартов ЖЦ ПС и других стандартов, регламен­тирующих шаблоны программных документов на различных этапах проекта. В результате создаются и применяются проблемно-ориентиро­ванные совокупности методических руководств, отражающие наиболее современные методы, формы и фрагменты документов, для документальной поддержки этапов и процессов жиз­ненного цикла ПС, определенного класса или функционального наз­начения.

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

Процессы документирования программ и данных входят в весь жизненный цикл сложных систем и ПС. Поэтому организация и реализация работ по созданию документов должны распределяться между специа­листами, ведущими непосредственное и преимущественное создание проектов комплексов программ и специалистами осуществляющими, в основном, разработ­ку, контроль и издание документов. При создании особо сложных систем целесообразно выделение специального кол­лектива, обеспечивающего организацию и реализацию основных сис­темных работ по документообороту ПС. Совокупные затраты на документирование крупных программных продуктов могут достигать 20 – 30% от общей трудоемкости проекта и необходимого числа (десятки) специалистов в жизненном цикле проекта ПС. В более простых случаях, ор­ганизация работ может быть упрощена, затраты на документирование снижаются приблизительно до 10%, однако всегда целесообразно выделять специалистов, непосредственно ответственных за создание, адекватность и контроль полноценного комплекта документов на программный продукт. Состав и общий объем документов широко варьируется в зависимости от класса и характеристик объекта раз­работки, а также в зависимости от используемой технологии. Наиболее сложному случаю разработки критических ПС реального времени высокого качест­ва соответствует самая широкая номенклатура документов. Такой перечень документов может быть использован как базовый для формирования на его основе состава и шаблонов документов в ос­тальных более простых проектах.

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

- технологическую документацию процессов разработки и обеспечения всего жизненного цикла, включаю­щую подробные технические описания, и подготавливаемую для спе­циалистов, ведущих проектирование, разработку и сопровождение комплексов программ, обеспечивающую возможность отчуждения, детального освоения, развития и корректировки ими программ и данных на всем жизненном цикле ПС;

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

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

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

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

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

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

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

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

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

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