Глава 16. Сопровождение программного обеспечения. Документирование результатов и хода разработки

Проблемы документирования

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

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

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

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

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

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

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

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

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

Виды документации

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

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

1. Эксплуатационная (или пользовательская) документация со­держит сведения, необходимые для работы с готовой программной системой. Она охватывает три круга вопросов: о назначении и областях применения системы, о правилах работы с ней, о действиях, необходимых для настройки системы в конкретных условиях эксплуатации и для поддержания ее в работоспособном состоянии.

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

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

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

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

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

Примерный состав технической документации может быть следующим:

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

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

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

4. описание методов решения поставленных задач и используемых при этом алгоритмов;

5. проекты модулей, описывающих интерфейсы каждого модуля его внутренние данные и структуру управления;

6. тексты программных модулей на языке реализации;

7. план тестирования программы, определяющий цели и поря­док тестирования отдельных моделей и компонентов, а также вспомогательные программные и технические средства, необходимые для проведения тестирования;

8. план тестирования каждого модуля (компонента), включа­ющий описание тестовых данных, используемых для проверки модуля, и ожидаемых для каждого теста результатов;

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

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

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

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

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