Документальное обеспечение ПО важно не только для последующей эксплуатации разработанных систем ПО, но и для процесса проектирования. Документация должна создаваться по ходу проектирования, часть ее разраба-тывается и используется непосредственно в процессе проектирования персо-налом групп разработки, на различных этапах создания проекта.
При разработке ПС создается и используется большой объем разно-образной документации. Она необходима как средство передачи информа-ции между разработчиками ПС, как средство управления разработкой ПС и как средство передачи пользователям информации, необходимой для приме-нения и сопровождения ПС. На создание этой документации приходится большая доля стоимости ПС. Эту документацию можно разбить на две группы: - документы управления разработкой ПС; - документы, входящие в состав ПС. Документы управления разработкой ПС (software process documentation) управляют и протоколируют процессы разработки и сопровождения ПС, обеспечивая связи внутри коллектива разработчиков ПС и между коллективом разработчиков и менеджерами ПС (software managers) - лицами, управляющими разработкой ПС. Эти документы могут быть следующих типов: - планы, оценки, расписания. Эти документы создаются менеджерами для прогнозирования и управления процессами разработки и сопровождения ПС; - отчеты об использовании ресурсов в процессе разработки. Созда-ются менеджерами; - стандарты. Эти документы предписывают разработчикам, каким принципам, правилам, соглашениям они должны следовать в процессе разра-ботки ПС. Эти стандарты могут быть как международными или националь-ными, так и специально созданными для организации, в которой ведется раз-работка ПС; - рабочие документы. Это основные технические документы, обес-печивающие связь между разработчиками. Они содержат фиксацию идей и проблем, возникающих в процессе разработки, описание используемых стра-тегий и подходов, а также рабочие (временные) версии документов, которые должны войти в ПС; - заметки и переписка. Эти документы фиксируют различные детали взаимодействия между менеджерами и разработчиками. Документы, входящие в состав ПС (software product documentation), описывают программы ПС как с точки зрения их применения пользователя-ми, так и с точки зрения их разработчиков и сопроводителей (в соответствии с назначением ПС). Здесь следует отметить, что эти документы будут ис-пользоваться не только на стадии эксплуатации ПС (в ее фазах применения и сопровождения), но и на стадии разработки для управления процессом разработки (вместе с рабочими документами) - во всяком случае, они долж-ны быть проверены (протестированы) на соответствие программам ПС. Эти документы образуют два комплекта с разным назначением: - пользовательская документация ПС (П-документация); - документация по сопровождению ПС (С-документация). Пользовательская документация ПС (user documentation) объясняет пользователям, как они должны действовать, чтобы применить разрабаты-ваемое ПС. Она необходима, если ПС предполагает какое-либо взаимодей-ствие с пользователями. К такой документации относятся документы, кото-рыми должен руководствоваться пользователь при инсталляции ПС (при ус-тановке ПС с соответствующей настройкой на среду применения ПС), при применении ПС для решения своих задач и при управлении ПС (например, когда разрабатываемое ПС будет взаимодействовать с другими системами). Эти документы частично затрагивают вопросы сопровождения ПС, но не ка-саются вопросов, связанных с модификацией программ. В связи с этим следует различать две категории пользователей ПС: ординарных пользователей ПС и администраторов ПС. Ординарный пользователь ПС (end-user) использует ПС для решения своих задач (в своей предметной области). Это может быть инженер, проек-тирующий техническое устройство, или кассир, продающий железнодорож-ные билеты с помощью ПС. Он может и не знать многих деталей работы компьютера или принципов программирования. Администратор ПС (system administrator) управляет использованием ПС ординарными пользователями и осуществляет сопровождение ПС, не связанное с модификацией программ. Например, он может регулировать права доступа к ПС между ординарными пользователями, поддерживать связь с поставщиками ПС или выполнять определенные действия, чтобы поддерживать ПС в рабочем состоянии, если оно включено как часть в дру-гую систему. Состав пользовательской документации зависит от аудиторий пользо-вателей, на которые ориентировано разрабатываемое ПС, и от режима ис-пользования документов. Под аудиторией здесь понимается контингент пользователей ПС, у которого есть необходимость в определенной пользова-тельской документации ПС. Удачный пользовательский документ сущест-венно зависит от точного определения аудитории, для которой он предназна-чен. Пользовательская документация должна содержать информацию, необ-ходимую для каждой аудитории. Под режимом использования документа по-нимается способ, определяющий, каким образом используется этот документ. Обычно пользователю достаточно больших программных систем требуются либо документы для изучения ПС (использование в виде инструкции), либо для уточнения некоторой информации (использование в виде справочника). В соответствии с работами можно считать типичным следующий со-став пользовательской документации для достаточно больших ПС: - общее функциональное описание ПС дает краткую характеристику функциональных возможностей ПС. Предназначено для пользователей, кото-рые должны решить, насколько необходимо им данное ПС; - руководство по инсталляции ПС предназначено для администрато-ров ПС. Оно должно детально предписывать, как устанавливать системы в конкретной среде, файлы, представляющие ПС, и требования к минимальной конфигурации аппаратуры;
- инструкция по применению ПС предназначена для ординарных пользователей. Содержит необходимую информацию по применению ПС, ор-ганизованную в форме удобной для ее изучения; - справочник по применению ПС предназначен для ординарных поль-зователей. Содержит необходимую информацию по применению ПС, органи-зованную в форме удобной для избирательного поиска отдельных деталей; - руководство по управлению ПС предназначено для администрато-ров ПС. Оно должно описывать сообщения, генерируемые, когда ПС взаимо-действует с другими системами, и как должен реагировать администратор на эти сообщения. Кроме того, если ПС использует системную аппаратуру, этот документ может объяснять, как сопровождать эту аппаратуру. Разработка пользовательской документации начинается сразу после создания внешнего описания. Качество этой документации может сущест-венно определять успех ПС. Она должна быть достаточно проста и удобна для пользователя (в противном случае, это ПС вообще не стоило создавать). Поэтому, хотя черновые варианты (наброски) пользовательских документов создаются основными разработчиками ПС, к созданию их окончательных вариантов часто привлекаются профессиональные технические писатели. Документация по сопровождению ПС (system documentation) описы-вает ПС с точки зрения ее разработки. Эта документация необходима, если ПС предполагает изучение того, как оно устроено (сконструировано), и мо-дернизацию его программ. Сопровождение - это продолжающаяся разра-ботка. Поэтому в случае необходимости модернизации ПС к этой работе привлекается специальная команда разработчиков-сопроводителей. Этой команде придется иметь дело с такой же документацией, которая определяла деятельность команды первоначальных (основных) разработчиков ПС, - с той лишь разницей, что эта документация для команды разработчиков-сопроводителей будет, как правило, чужой (она создавалась другой коман-дой). Чтобы понять строение и процесс разработки модернизируемого ПС, команда разработчиков-сопроводителей должна изучить эту документацию, а затем внести в нее необходимые изменения, повторяя в значительной сте-пени технологические процессы, с помощью которых создавалось первона-чальное ПС. Документацию по сопровождению ПС можно разбить на две группы: - документация, определяющая строение программ и структур дан-ных ПС и технологию их разработки; - документация, помогающая вносить изменения в ПС. Документация первой группы содержит итоговые документы каждо-го технологического этапа разработки ПС. Она включает следующие доку-менты: - внешнее описание ПС (Requirements document); - описание архитектуры ПС, включая внешнюю спецификацию каж-дой ее программы (подсистемы); - для каждой программы ПС - описание ее модульной структуры, включая внешнюю спецификацию каждого включенного в нее модуля; - для каждого модуля - его спецификация и описание его строения;
- тексты модулей на выбранном языке программирования;
- документы установления достоверности ПС, описывающие, как устанавливалась достоверность каждой программы ПС и как информация об установлении достоверности связывалась с требованиями к ПС.
Документы установления достоверности ПС включают, прежде всего, документацию по тестированию (схема тестирования и описание комплекта тестов). Документация второй группы содержит руководство по сопровожде-нию ПС, которое описывает особенности реализации ПС (в частности, труд-ности, которые пришлось преодолевать) и как учтены возможности развития ПС в его строении (конструкции). В нем также фиксируются, какие части ПС являются аппаратно- и программно-зависимыми. Общая проблема сопровождения ПС - обеспечить, чтобы все его представления шли в ногу (оставались согласованными), когда ПС изменяет-ся. Чтобы этому помочь, связи и зависимости между документами и их час-тями должны быть отражены в руководстве по сопровождению, и зафикси-рованы в базе данных управления конфигурацией.
