Проблеми організації документування

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

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

- выявить заинтересованных лиц и пользователей документов, чье коллективное мнение в конечном итоге определяет успех или неудачу проекта и его документации;

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

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

- выделить основные причины и источники, определяющие появление проблем документирования;

- понять ограничения, которые могут сопутствовать или препятствовать решению проблем документирования.

 

Рис. 1.1

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

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

- интервьюирование и анкетирование заказчиков и потенциальных пользователей;

- совещания, посвященные анализу требований к проекту и его документам;

- прецеденты и аналоги успешных проектов программных средств;

- имитацию функционирования разработчиков и пользовате­лей при использовании различных документов;

- создание и апробацию прототипов и версий документов.

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

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

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

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

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

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

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

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

- принята - функции, которые официальный орган заказчика признал полезными и достижимыми и допустил к реализации;

- включена - функции, включенные в базовый уровень и документы ПС на данный момент времени.

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

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

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

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

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

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

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

Размер первоначальной версии обобщает основные запланированные функции, включенные в базовую версию программного продукта. Зарегистрированные характеристики качества, позволят продукту предоставлять предполагаемые выгоды различным классам пользователей. Если задача - сосредоточиться на разработке и уложиться в график, следует избегать искушения включать в первую версию каждую функцию, которая когда-нибудь в будущем может понадобиться какому-то потенциальному покупателю. Увеличение сроков и сдвиг графика — типичный результат такого расползания масштаба. Следует сосредоточиваться на наиболее ценных функци­ях, имеющих приемлемую стоимость, годных для самой широкой целевой аудитории, которые позволят создать проект как можно раньше.

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

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

В процессе установления стратегии, стандартов и руководств по документированию конкретного проекта ПС необходи­мо осуществить - см. рис. 1.1:

- выбор модели жизненного цикла ПС и состава его докумен­тов (рис. 1.2);

- определение шаблонов, содержания и степени детализации
каждого документа;

- определение необходимого качества каждого документа;

- определение форматов и системы обозначения документов;

- установление процедур реализации шаблонов документов;

- распределение ресурсов для документирования: персонала; технических средств; финансов, а также на планирование документирования.

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

 

 

 

Рис. 1.2

Проблемы организационной структуры коллектива, обеспечивающего документирование при создании и развитии конкрет­ных комплексов программ и данных определяют - см. рис. 1.1. [2,4,11,19]:

- состав подразделений и должностных лиц предприятия,

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

- основные функции и связи между подразделениями и отдельными должностными лицами, указанными на схеме документирования, и их подчиненность;

- описание регламента работ документирующих подразделений;

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

Стратегия разработки, совершенствования, расширения функ­ций и сферы применения ПС требует перехода к определенному, регламентированному порядку, который позволит специалистам в этой области говорить на одном языке и сделать процессы документирования программ и баз данных экономически эффективными (см. п. 1.4). Создание и сопровождение документации на ПС должны обеспечивать длительный жизненный цикл, мобильность и повтор­ное применение программных и информационных компонентов, независимо от их первичных разработчиков. Представленный ниже (п. 1.5 и гл. 3) порядок документирования охватывает весь жизненный цикл программных средств от формирования концепции и требова­ний к первой версии ПС до завершения его жизненного цикла. Общая структура и комплекс шаблонов технологических и эксплуата­ционных документов объектов и процессов ЖЦ ПС, предназначены для использования в индустрии сложных систем управления и обработки информации. Эта структура содержит номенклатуру документов, которые должны быть использованы во время создания, приме­нения и сопровождения программных средств, для определения, Управления и совершенствования сложных комплексов программ. Предприятие, подразделение или руководство конкретного проекта, в зависимости от стоящей перед ними задачи, могут выбрать соответствующую группу документов, процессов и процедур для реализации своей конкретной цели. Они предназначены для использова­ния в тех случаях, когда программный продукт и его документация

является автономным объектом или встроенной и неотъемлемой частью системы. Для этого организаторы документирования и заказ­чики должны обеспечить специалистов, создающих ПС [4, 10, 16,17]:

- официальными отчетами и руководствами по принятой стратегии документирования конкретного проекта ПС;

- стандартами и нормативными документами, определяющими все аспекты документирования программ и данных;

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

- вычислительными, трудовыми и временными ресурсами для реализации документирования программ и данных;

- планами документирования как органической части всего жизненного цикла конкретного ПС;

- контролем, управлением и консультациями для обеспечения полноценного и унифицированного документирования всех компонентов и процессов ЖЦ ПС.

Проблема согласования и утверждения требований заказчи­ка и разработчиков на проект и документацию программного средства должны осуществляться, используя при этом принятую в соответствующем бизнесе терминологию - см. рис. 1.1. [3, 7, 11, 24]. Выявляя требования заказчика, аналитики и менеджеры разработчика могут лучше понять задачи и осознать, какое место уготовано создаваемому ПС у заказчика. Аналитики должны отсортировать и выявить функциональные требования, цели и возможные решения в области создания и применения ПС. Конечный итог этого анализа - спецификация требований к программному средству и документам, представляющая собой соглашение между разработчиками и заказчиком о функциях, качестве, документах и ограничениях создаваемого продукта. Чтобы гарантировать, что новая система не будет автоматизировать неэффективные или устаревшие процессы, аналитики должны знать, почему существующие системы не годятся для заказчика. Иногда пользователи просят, чтобы продукт был дружественным, надежным или эффективным, однако эти термины слишком субъективны, чтобы помочь разработчикам. Поэтому аналитики должны выяснять и документировать конкретные характеристики, означающие эти пожелания.

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

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

Проблема, влияющая на выбор методов и технологии документирования, может быть объединена общим понятием -доступные ресурсы разработки - рис. 1.1.[6, 13, 22] Они включают реальные финансовые, кадровые и аппаратурные ограничения, в условиях которых предстоит разработка документов ПС. Некоторые ресурсы однозначно предопределяют параметры средств автоматизации разработки, а другие более или менее существенно влияют на выбор технологий и номенклатуры разрабатываемых документов.

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

Проблемы прогнозирования физического объема комплекса документов для конкретных проектов программного средства - см. рис. 1.1. Базой для таких оценок можно использовать соответствующую модель жизненного цикла ПС. Последующее изложение базируется на применении сокращенной каскадной модели жизнен­ного цикла сложных программных средств (см. стандарт ГОСТ Р 16326), представленной на рис. 1.2, которая используется в п. 1.5 и главе 3 при структурировании групп шаблонов документов, поддерживающих выделенные этапы ЖЦ ПС. Ниже приводятся рекомендации по структуре и содержанию более шестидесяти шаблонов типовых документов, сконструированных так, что возможны их выбор и адаптация в соответствии с масштабом и характеристиками проектов ПС. Адаптация является процессом в основном исключения процедур и компонентов документов, не применимых в конкретном проекте. Добавление уникальных или специфических документов должно быть оговорено в контракте или конкретной методике. Архитектура и содержание шаблонов документов на ПС, далее не конк­ретизируется в деталях, как их реализовать, оформить и оценить суммарный объем комплекса документов для определенного проекта, вследствие большого числа неопределенных параметров. Эти задачи должны решаться индивидуально с использованием Руководящих документов по подготовке и оформлению конкретных эксплуатационных и технологических документов для пользователей и разработчиков определенных проектов ПС. Стороны ответ­ственны за выбор и применение методов и инструментальных средств автоматизации разработки и оценки суммарных размеров совокупности документов, а также за выбор процедур и документов, подходящих для оценки конкретного проекта ПС или системы.

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

- договоров между заинтересованными лицами проектов ПС;

- описаний компонентов, процессов и продуктов комплексов программ;

- руководств по разработке и применению программных средств;

- планов выполнения работ и процессов разработки документов;

- протоколов результатов и контроля качества процессов или продуктов;

- отчетов о проделанной работе или испытаниях программных продуктов;

- справочников о функциях и эксплуатации программных средств;

- учебных пособий для освоения и применения программных средств пользователями.

Следует учитывать возможные ограничения, связанные с форматированием и печатью. Многие проекты комплексов программ предлагают для помощи пользователям систему интерактивных подсказок. Подобные системы имеют уникальную природу: они сочетают в себе моменты программирования (создание гиперссылок) с моментами написания технических текстов. Могут быть важны применения некоторых компонентов ПС - руководства по инсталляции, инструкции по конфигурированию. В качестве стандартного компонента иногда включается файл Read Me. Он может содержать разделы описаний продукта, что нового в очередной версии и обсуждение совместимости с более ранними версиями.

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